@harperfast/template-react-ts-ssr-studio 1.13.4 → 1.13.5

package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md

@@ -28,54 +28,62 @@ metadata:
       Actions
     - reference/v5/operations-api/operations.md#`list_oidc_trust`
     - reference/v5/operations-api/operations.md#`drop_oidc_trust`
-  sourceCommit: 2dde0597443a13af0c753f2adbe528e8442d8ee4
-  inputHash: b235eb6a7fb4d9a1
+  sourceCommit: e69702c99845f2dd810cb32652d1a9e6b58c538b
+  inputHash: 91e58cd0833af162
 ---
 
 # Deploying a Harper Application from GitHub Actions with OIDC
 
-Instructions for the agent to configure and execute credential-free Harper deployments from GitHub Actions using OIDC trusted publishing, including one-command setup and complete workflow examples.
+Instructions for the agent to configure and use OIDC trusted publishing so a GitHub Actions workflow can deploy to Harper with no stored credential.
 
 ## When to Use
 
-Apply this rule when asked to deploy from CI, to set up or fix a deploy workflow (including the `.github/workflows/deploy.yaml` that create-harper projects ship), or to move a pipeline off a stored Harper credential such as `HARPER_CLI_REFRESH_TOKEN`. Use it when setting up OIDC trust for the first time, writing or debugging a deploy workflow, or revoking/rotating pipeline access.
+Apply this rule when wiring up a GitHub Actions workflow to deploy a Harper application without storing a `HARPER_CLI_REFRESH_TOKEN` or any other durable credential in CI. Use it both for the one-command setup path (branch-triggered deploys) and for the manual policy path (tag-triggered releases). Also apply it when diagnosing a rejected OIDC exchange or revoking pipeline access.
 
 ## How It Works
 
-### One-Command Setup (Branch-Based Deploys)
+### One-Command Setup (branch-triggered deploys)
 
-1. **Run setup once** from the project checkout, signed in as a `super_user`:
+1. **Run setup once** from the project's checkout, signed in as a `super_user`:
 
    ```bash
-   harper login https://my-cluster.example.com:9925
    harper deploy setup=true provider=github-actions project=my-app
    ```
 
-   If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=` explicitly — otherwise the policy pins `deploy.yaml` and runs of your workflow cannot match it:
+   If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=`:
 
    ```bash
    harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
    ```
 
-2. **Understand what setup does** — in order:
-   - Resolves the GitHub repository's numeric id and canonical name from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` when the API is unavailable (e.g., private repo without `gh`).
-   - **The workflow is checked before anything is written.** It must be able to run on `main` (`branch=`) and run a job in the `production` environment (`environment=`) with `permissions: id-token: write`; one that never could stops setup. What it can't decide is reported as not verified.
-   - Creates a role and a user named `<project>-ci-deploy` with permissions limited to `deploy_component`, `get_job`, and `registration_info`, and a trust policy named `github-actions-<project>`.
-   - Reads the policy back and compares it claim by claim with what it intended to write.
-   - Sets the repository's `HARPER_CLI_TARGET` Actions variable via `gh` if one does not already exist.
+2. **Understand what setup does** — it executes these steps automatically:
+   - Resolves the GitHub repository's numeric `repository_id` from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` explicitly for private repos without `gh`.
+   - Validates the workflow file: it must be able to run on `main` (or `branch=`), run a job in the `production` environment (`environment=`), and grant `id-token: write`. Setup stops before writing anything if the workflow could never match or never request a token.
+   - Creates a role and a user named `<project>-ci-deploy` with permissions limited to `deploy_component`, `get_deployment`, `get_job`, and `registration_info`, plus the trust policy `github-actions-<project>`.
+   - Reads the policy back and compares it claim by claim.
+   - Sets the repository's `HARPER_CLI_TARGET` variable via `gh` if one does not already exist.
 
-3. **Handle idempotency**: setup only creates — it never updates. A role, user, or policy that already exists but differs stops setup and names what differs. To replace a policy:
+3. **Handle idempotency**: setup only creates — it never overwrites. A role, user, or policy that already exists but differs stops setup before writing. To replace a policy:
 
    ```bash
    harper drop_oidc_trust id=github-actions-<project>
-   harper deploy setup=true provider=github-actions project=my-app
    ```
 
-### Manual Setup (Tag-Based or Custom Deploys)
+   Then run setup again.
+
+---
+
+### Manual Setup (tag-triggered deploys)
 
-Use this path when deploying on version tags, because a branch-pinned policy cannot match a tag ref.
+Use this path when the workflow deploys on version tags, because a branch pin cannot match a tag ref.
 
-1. **Create a deploy-only role and user**:
+1. **Log in as `super_user`**:
+
+   ```bash
+   harper login https://my-cluster.example.com:9925
+   ```
+
+2. **Create a deploy-only role and user** named `<project>-ci-deploy`:
 
    ```bash
    harper add_role role=ci_deploy permission='{"operations":["deploy_component","get_job","get_deployment","registration_info"]}'
@@ -83,12 +91,12 @@ Use this path when deploying on version tags, because a branch-pinned policy can
    ```
 
    - `deploy_component` — the deploy itself.
-   - `get_job` — required for the wait step; an `operations` allowlist refuses anything not listed, so without it the wait step fails with `403`.
-   - `get_deployment` — reads the deployment record.
-   - `registration_info` — version check `harper deploy` makes before uploading.
+   - `get_deployment` — required for `harper deploy restart=rolling` to wait on every node; without it that wait fails with `403`.
+   - `get_job` — required for the wait step; without it the wait step fails with `403`.
+   - `registration_info` — version check before upload; omitting it logs a refused operation on every run.
    - `restart_service` is not needed: Harper starts the rolling restart's job itself. The password is required to create the user but a GitHub Actions pipeline never uses it, so this command discards it.
 
-2. **Add a trust policy** pinned to `repository_id`, `workflow_path`, and `environment` (use this shape when the tag is unknown at policy-write time):
+3. **Add a trust policy** pinning `repository_id`, `workflow_path`, and `environment` (use this shape for tag-triggered workflows where `workflow_ref` cannot be pinned):
 
    ```bash
    harper add_oidc_trust \
@@ -100,45 +108,40 @@ Use this path when deploying on version tags, because a branch-pinned policy can
    ```
 
    Key claim rules:
-   - `repository_id` is immutable — survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
-   - `workflow_path` pins the workflow file. Harper derives it from the token's `workflow_ref` by removing the `@<ref>` suffix, so it is `<owner>/<repo>/<path>`.
+   - `repository_id` is immutable and survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
+   - `workflow_path` is derived from `workflow_ref` by removing the `@<ref>` suffix; format is `<owner>/<repo>/<path>`.
    - `environment` is the ref gate. Without it, anyone who can push a branch can mint a token.
    - `audience` must be the exact target URL with its port and a **trailing slash**.
    - A workflow that deploys on a push to `main` can pin `workflow_ref` (`my-org/my-app/.github/workflows/deploy.yml@refs/heads/main`) instead, which gates the ref by itself.
 
-3. **Configure the GitHub environment**: in **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern. Add required reviewers if a release needs approval.
+4. **Configure the GitHub environment**: in **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern. Add required reviewers if a release needs approval.
 
-4. **Store the target as a repository variable** (not a secret — it is not sensitive):
+5. **Store the target as a repository variable** (not a secret):
 
    ```bash
    gh variable set HARPER_CLI_TARGET --repo my-org/my-app --body https://my-cluster.example.com:9925/
    ```
 
+---
+
 ### How OIDC Authentication Works in the Workflow
 
-Once a trust policy exists, every `harper` command in the deploy job authenticates through it automatically when all four conditions hold:
+A job authenticates automatically when all four conditions hold:
 
-1. **The job may request an identity token.** On GitHub Actions that is `permissions: id-token: write` on the job.
-2. **`HARPER_CLI_TARGET` is the policy's `audience`.** The CLI requests its token for the target it connects to, so the target must be the URL the policy names, with its port and trailing slash. Use `vars.HARPER_CLI_TARGET` — it is not sensitive, so a repository variable rather than a secret.
-3. **The run matches the policy's claims**: its repository, its workflow file and branch, and its environment.
+1. **The job declares `permissions: id-token: write`.**
+2. **`HARPER_CLI_TARGET` is the policy's `audience`.** The CLI requests its token for the target it connects to, so the target must be the URL the policy names, with its port and trailing slash. It is not sensitive, so use `vars.HARPER_CLI_TARGET` rather than a secret.
+3. **The run matches the policy's claims**: its `repository_id`, `workflow_path`/`workflow_ref`, and `environment`.
 4. **Nothing else is configured to authenticate.** `auth_username=`/`auth_password=`, credentials in the target URL, `HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`, `HARPER_CLI_REFRESH_TOKEN` or `HARPER_CLI_OPERATION_TOKEN`, and a saved `harper login` all outrank the exchange.
 
-What each command may then do is up to the role of the user the policy names: a role that lists only `deploy_component`, `get_job` and `registration_info`, like the one setup creates, refuses anything else with a `403`.
+Nothing in the workflow names the policy. Every `harper` command in the job (`harper deploy`, `harper get_job`, etc.) authenticates through it automatically.
 
 The exchange runs only when GitHub sets `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, which it does for a job that declares `permissions: id-token: write`. Without them, the CLI falls through to its other credential sources rather than reporting a failure.
 
-Nothing in the workflow names the policy. The CLI prints to stderr which policy authenticated it and as whom:
-
-```
-Requesting a GitHub Actions identity token for https://my-instance.harperdb.io:9925/...
-Authenticated as 'ci-deploy' via OIDC trust policy 'my-app-prod'.
-```
-
-Diagnose a rejected exchange with `list_oidc_trust` (check for `invalid_reason` on each entry) and the instance's `oidc-trust` log. The server deliberately does not report which check failed.
+---
 
 ### Policy Specificity for GitHub Actions
 
-For `https://token.actions.githubusercontent.com`, a policy must satisfy all three of these:
+For `issuer=https://token.actions.githubusercontent.com`, every policy must satisfy all three requirements:
 
 | Requirement            | Satisfied by one of                                                      | Left open otherwise                             |
 | ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
@@ -148,21 +151,68 @@ For `https://token.actions.githubusercontent.com`, a policy must satisfy all thr
 
 Additional constraints:
 
-- `repository_id` is preferred over `repository` — it is immutable and survives renames.
-- A tag-triggered release cannot pin `workflow_ref` since the tag is unknown when the policy is written. Pin `workflow_path` and gate on `environment`.
 - `ref_type: tag` is not accepted as a ref gate, `sub` is not accepted as a pin, and `job_workflow_ref` pins the workflow without gating the ref. `pull_request_target` runs are denied unless the policy constrains `event_name`.
 
-### Revoking Access
+---
+
+### Diagnosing a Rejected Exchange
+
+Run `list_oidc_trust` (requires `super_user`) to list all policies including disabled ones:
+
+```json
+{ "operation": "list_oidc_trust" }
+```
+
+`list_oidc_trust` returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, and optionally `invalid_reason`. Check `invalid_reason` first when diagnosing a rejected exchange — it is set when the policy is malformed or its user was deleted or deactivated after the policy was written. The exchange itself will not report what failed.
+
+Check the instance's `oidc-trust` log for server-side detail.
+
+---
+
+### Revoking Pipeline Access
+
+- **Stop future runs** — drop the policy:
+
+  ```bash
+  harper drop_oidc_trust id=github-actions-<project>
+  ```
+
+  This does not revoke tokens already issued (they are stateless JWTs valid for one hour).
+
+- **Stop a token already in circulation** — deactivate the user:
+
+  ```bash
+  harper alter_user username=<project>-ci-deploy active=false
+  ```
+
+  Use both together when responding to a suspected compromise.
 
-- **Stop future runs**: `harper drop_oidc_trust id=github-actions-<project>` (does not revoke already-issued tokens, which are valid up to one hour).
-- **Stop an already-issued token**: `harper alter_user username=<project>-ci-deploy active=false`.
-- **No CI secret to rotate** — there is none.
+---
+
+### Providing a Durable Credential for a Private Source
+
+Do not use the workflow's ephemeral `GITHUB_TOKEN` for Harper's stored credential — it expires when the job ends, and later installs (a new node joining, a reinstall after restore) would fail. Instead use a durable token:
+
+- For a private repository: a fine-grained personal access token with **Contents: read-only** scoped to the application repository.
+- For GitHub Packages: a token with the `read:packages` scope.
+
+Store it in Harper once from your machine:
+
+```bash
+# Private git repository
+harper deploy setup=true provider=github project=my-app
+
+# GitHub Packages
+harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
+```
+
+The name is derived from the component and the host: `deploy.my-app.git.github.com` for the repository, and `deploy.my-app.npm.pkg.github.com` for GitHub Packages. Reference it by that name in the workflow — the token never appears in your pipeline.
 
 ## Examples
 
 ### Path A: Deploy a Tagged Release (`v1.2.3`) from the Repository
 
-Push a semver tag (`v1.2.3`), and every node clones and installs that commit. `by_ref=true` deploys `git+https://github.com/<owner>/<repo>.git#<sha>`, where the SHA is the commit the tag points to (`GITHUB_SHA`), and every node clones that exact commit even if the tag moves later. For a private repository, add `credential=true` to attach the stored credential (`deploy.my-app.git.github.com`). If the repository needs a build step to be runnable, don't reach for `install_allow_scripts`: use Path B.
+Push a semver tag (`v1.2.3`), and every node clones and installs that commit. `by_ref=true` deploys `git+https://github.com/<owner>/<repo>.git#<sha>`, where the SHA is the commit the tag points to (`GITHUB_SHA`), and every node clones that exact commit even if the tag is moved later. If this repository needs a build step to be runnable, do not reach for `install_allow_scripts` — use Path B instead.
 
 ```yaml
 # .github/workflows/deploy.yml
@@ -192,6 +242,8 @@ jobs:
         run: harper deploy project=my-app by_ref=true restart=rolling json=true > deploy.json
       - name: Wait for every node to take the release
         run: |
+          # From v5.4.0 a certified rolling deploy waited for every node itself.
+          [ "$(jq -r '.rollout.status // empty' deploy.json)" != success ] || exit 0
           JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
           [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
           LAST="could not be read"
@@ -212,14 +264,17 @@ jobs:
 Key details:
 
 - **No secrets.** `HARPER_CLI_TARGET` is the only thing the workflow is given. `id-token: write` lets the CLI request an identity token, and `environment: production` puts the `environment` claim the trust policy requires into it.
-- **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`.
+- **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`, where `actions/checkout` otherwise leaves it for every later step.
 - **`harper@^5.3`** pins the CLI's major version. 5.3 is the first CLI that authenticates with the identity token.
 - **`replicated` isn't needed.** On Harper Fabric and Harper Pro, a deploy goes to every node unless you pass `replicated=false`. Each node fetches and installs the package itself.
-- **`restart=rolling`** restarts nodes one at a time. Use `restart=true` for a single-node or dev instance.
-- **`json=true`** prints the deploy's result as JSON on stdout; progress and authentication messages go to stderr.
-- **The wait step** polls `restartJobId` via `get_job` until `COMPLETE` or `ERROR`, checking `.[0].status`. It retries a poll that fails (such as one that reaches a node while it restarts) and gives up after 60 polls (~10 minutes).
-- **`certification`**: on v5.4.0 and later, `restart=rolling` loads the release in a canary worker on each node before that node serves it, so a release that fails to load is rejected. The `certification` field in the deploy result reflects this. With `restart=rolling` on v5.4.0 and later, the deploy can report `success` before the rolling job has visited all nodes — wait on the job, not the record.
-- **The job lives on one node.** Through a **load-balanced** cluster URL, polls must eventually reach that node. Routing that always sends polls to a different node than the deploy causes the wait step to fail saying the job was not on the node that answered.
+- **`restart=rolling`** restarts nodes one at a time so the cluster keeps serving throughout. Use `restart=true` for a single-node or dev instance.
+- **`certification`**: on v5.4.0 and later, `restart=rolling` loads the release in a canary worker on each node before that node serves it, so a release that fails to load is rejected. The `certification` field in the deploy result reflects whether this ran.
+- **`restartJobId`**: present in the deploy JSON when a rolling job was started but the deploy did not wait for it itself. The wait step polls `.[0].status` from `get_job` until `COMPLETE` or `ERROR`.
+- **Load-balanced clusters**: the deployment record wait works through a load-balanced URL (the record replicates), but `get_job` polls do not — Harper does not replicate jobs. If your load balancer never routes back to the node that received the deploy, use one node's direct URL for both the deploy and the wait, and as the trust policy's `audience`.
+
+For a private repository, add `credential=true` to the deploy command.
+
+---
 
 ### Path B: Build in CI, Publish to GitHub Packages, Deploy the Artifact
 
@@ -288,6 +343,7 @@ jobs:
             restart=rolling json=true > deploy.json
       - name: Wait for every node to take the release
         run: |
+          [ "$(jq -r '.rollout.status // empty' deploy.json)" != success ] || exit 0
           JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
           [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
           LAST="could not be read"
@@ -305,54 +361,26 @@ jobs:
           exit 1
 ```
 
-Two jobs keep the identity token isolated: `publish` installs, builds, tests and publishes with `contents: read` and `packages: write` only — it cannot request an identity token. `deploy` runs once `publish` finishes (`needs: publish`), holds `environment: production` and `id-token: write`, and installs only the Harper CLI before deploying.
-
-Credential roles:
-
-- **Publishing** and installing private `@my-org` dependencies use the workflow's ephemeral `GITHUB_TOKEN` (`packages: write` includes read). Both happen entirely inside `publish`.
-- **Installing on Harper nodes** uses the durable `read:packages` token stored as `deploy.my-app.npm.pkg.github.com` — because installs can happen long after this workflow ends.
+Split into two jobs so the job with `id-token: write` runs none of your build code. Only the `deploy` job names `environment: production`, so only its token carries the `environment` claim the trust policy requires.
 
-For `my-app`, the credential names are `deploy.my-app.git.github.com` for the repository and `deploy.my-app.npm.pkg.github.com` for GitHub Packages. Store a durable credential once from your machine:
-
-```bash
-harper deploy setup=true provider=github project=my-app
-# or for GitHub Packages:
-harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
-```
-
-For a private repository, use a GitHub fine-grained personal access token with **Contents: read-only** scoped to the application repository. For GitHub Packages, use a token with the `read:packages` scope. Do not use the workflow's ephemeral `GITHUB_TOKEN` for the durable credential — it expires when the job ends.
+---
 
-### Check the Deployment Record
+### Checking the Deployment Record
 
 ```bash
 harper get_deployment deployment_id="$(jq -r .deployment_id deploy.json)" json=true
 ```
 
-Only the node you called writes that record, so with `restart=rolling` on v5.4.0 and later it can report `success` before the job has visited the other nodes, and keeps reporting it if one of them rejects the release. Wait on the job, not the record, to confirm all nodes took the release. `list_deployments` gives the history of what was deployed and when.
+Use `list_deployments` to see the history of what was deployed and when, and filter by commit with `sha`.
 
-### List and Inspect Trust Policies
-
-```bash
-harper list_oidc_trust
-```
-
-Returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, and optionally `invalid_reason`. Check `invalid_reason` first when diagnosing a rejected exchange — it is set when the policy is malformed or its user was deleted or deactivated.
-
-### Drop a Trust Policy
-
-```bash
-harper drop_oidc_trust id=github-actions-<project>
-```
+- **Go back to a previous release** by activating its `deployment_id`, with no rebuild or reinstall: `harper deploy project=my-app deployment_id=<id> restart=rolling`. To deploy a release that is no longer kept, re-run the deploy with its tag or version.
 
 ## Notes
 
-- `HARPER_CLI_REFRESH_TOKEN` and any other stored credential outrank the OIDC exchange. Remove them from the workflow if switching to OIDC.
-- **Go back to a previous release** by activating its `deployment_id`, with no rebuild or reinstall: `harper deploy project=my-app deployment_id=<id> restart=rolling`. To deploy a release that is no longer kept, re-run the deploy with its tag or version.
-- **Rotating the deploy credential**: run `harper deploy setup=true` again with the same name and a new value. The pipeline doesn't change.
-- **Revoking the pipeline's access**: `harper drop_oidc_trust` stops new runs; `harper alter_user` also stops a token already issued (valid up to one hour).
-- The `<project>-ci-deploy` user created by setup can deploy any component on the cluster, not only the named project. Access control comes down to who can merge to the branch.
-- The `audience` in `add_oidc_trust` must be the exact target URL with its port and a trailing slash.
-- For tag-triggered workflows, `provider=github-actions` setup is not sufficient — it pins a branch. Write the policy manually using `add_oidc_trust` with `workflow_path` and `environment` claims.
-- `token.actions.githubusercontent.com` is the required `issuer` value for GitHub Actions OIDC policies.
-- Git-host credentials require git ≥ 2.31 on the Harper nodes and are not supported on Windows nodes. Registry credentials have no such constraints.
+- `audience` in `add_oidc_trust` must include the port and a **trailing slash** — e.g., `https://my-cluster.example.com:9925/`. A URL without the trailing slash will not match.
+- `HARPER_CLI_REFRESH_TOKEN` and any other configured credential (`auth_username=`/`auth_password=`, `HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`, `HARPER_CLI_OPERATION_TOKEN`, a saved `harper login`) outrank the OIDC exchange. Remove stored credentials from the runner before enabling OIDC.
+- `list_oidc_trust`, `drop_oidc_trust`, and `alter_user` all require `super_user`.
+- `drop_oidc_trust` does not revoke already-issued operation tokens (one-hour JWTs). Pair it with `alter_user username=<project>-ci-deploy active=false` to stop tokens already in circulation.
+- `ref_type: tag` is not accepted as a ref gate. Gate tag-triggered workflows with `environment` instead, and set **Deployment branches and tags** to `v*` in the environment's settings.
+- Every step in a job with `id-token: write` can request an identity token — GitHub gives each one `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`. Run none of the repository's code in that job.
 - See [deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) for cluster-level deployment context.