@azx-pbc/helix-cli 0.4.0 → 0.5.0

package/README.md

@@ -67,6 +67,8 @@ helix versions                                               # list versions
 helix promote  <number>                                      # make a version live
 helix rollback [number]                                      # revert the live pointer
 helix skill    [--path <file>]                               # write this deployment's agent skill to disk
+helix ci init  [--repo <owner/name>] [--branch <b>] [--reusable] [--force]   # deploy from GitHub Actions
+helix ci show | helix ci remove                              # the app's repo binding
 ```
 
 `deploy` uploads the bundle as a **preview**; `--promote` flips it live in the
@@ -80,6 +82,36 @@ in. It needs no app slug or `helix.json`, only a portal URL and a token. Default
 `./SKILL.md`; `--path .claude/skills/helix/SKILL.md` drops it where a Claude Code
 agent reads it off disk.
 
+### Deploying from GitHub Actions
+
+`helix ci init`, run signed in from the app's directory in its repo checkout,
+connects the app to the repo and branch. The repo comes from `origin`; the
+branch is the remote's default branch. `--repo` and `--branch` override either.
+It then writes `.github/workflows/helix-deploy.yml` and merges `slug`,
+`portalUrl` and `dir` into `helix.json`, or into a legacy `azx.json` if that's
+the file in use. Commit both. Each push to the branch then lands a preview
+(ADR-0051). Re-running it keeps any environment or workflow limit set on the
+Repository tab, and refuses to replace a workflow pin unless you pass `--force`.
+
+The generated workflow has two jobs. `build` installs and builds with no
+`id-token` permission. `deploy` downloads the output and runs only the pinned
+CLI. Code from the repo or its dependencies never runs where it could mint a
+deploy token.
+
+The workflow needs no secret. Inside GitHub Actions, when `HELIX_TOKEN` is not
+set and the job has `permissions: id-token: write`, `helix deploy` asks GitHub
+for an OIDC token whose audience is the portal (read from `GET /api/v1/config`)
+and uploads to `POST /api/v1/apps/:slug/ci/versions`. CI deploys always land as
+a preview, so `--promote` is refused there. It refuses to send the token to a
+plain-`http` portal other than one on `localhost`.
+
+`--reusable` writes a caller of the public reusable workflow
+(`AZX-PBC-OSS/helix-actions`, source in `integrations/helix-actions/`) instead
+of a self-contained one. It also pins the binding to that workflow, so no other
+workflow on the branch can deploy. `helix ci show` prints the binding,
+including the repo ids pinned by the first deploy. `helix ci remove` disconnects
+the app.
+
 > **Breaking in 0.2.0:** the `private` visibility mode was renamed to `internal`.
 > It never checked _which_ user signed in, only that someone had. Passing the old
 > value now **errors** rather than mapping to the new one, deliberately: the name
@@ -91,9 +123,11 @@ agent reads it off disk.
 Two paths, in precedence order:
 
 1. **Static token** — `HELIX_TOKEN` / `--token`. Sends the value as a bearer
-   token verbatim. This is the CI/scripts path, and also how the portal's
-   dev-token stub keeps working (`HELIX_TOKEN=$PORTAL_DEV_TOKEN`). It is never
-   accepted by a production portal.
+   token verbatim. This is the local scripts path, and also how the portal's
+   dev-token stub keeps working (`HELIX_TOKEN=$PORTAL_DEV_TOKEN`). The dev token
+   is never accepted by a production portal. A stored token is not a supported
+   way to deploy from CI; repo-backed deploys use the workflow's GitHub Actions
+   OIDC token instead (ADR-0051).
 2. **`helix login`** — the OIDC device flow. The CLI asks the portal
    (`GET /api/v1/auth/config`) which issuer to use (the local dev IdP on
    `:3002` in dev; Entra later), prints a verification URL + code, and polls