@harperfast/template-vue-studio 1.13.6 → 1.13.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
  2. package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  3. package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  4. package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
  5. package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  6. package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  7. package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  8. package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
  9. package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  10. package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  11. package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  12. package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  13. package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  14. package/.agents/skills/harper-mcp/AGENTS.md +228 -155
  15. package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  16. package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  17. package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
  18. package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
  19. package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  20. package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  21. package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
  22. package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  23. package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  24. package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  25. package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
  26. package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  27. package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  28. package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  29. package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  30. package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  31. package/agent/skills/harper-mcp/AGENTS.md +228 -155
  32. package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  33. package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  34. package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
  35. package/package.json +1 -1
  36. package/skills-lock.json +2 -2
@@ -28,191 +28,127 @@ metadata:
28
28
  Actions
29
29
  - reference/v5/operations-api/operations.md#`list_oidc_trust`
30
30
  - reference/v5/operations-api/operations.md#`drop_oidc_trust`
31
- sourceCommit: e69702c99845f2dd810cb32652d1a9e6b58c538b
32
- inputHash: 91e58cd0833af162
31
+ sourceCommit: 489477b2259ba148f4e526ea4b5cd24041ceec03
32
+ inputHash: e56285cb04eaf135
33
33
  ---
34
34
 
35
35
  # Deploying a Harper Application from GitHub Actions with OIDC
36
36
 
37
- Instructions for the agent to configure and use OIDC trusted publishing so a GitHub Actions workflow can deploy to Harper with no stored credential.
37
+ Instructions for the agent to configure OIDC trusted publishing so a GitHub Actions workflow can deploy to Harper with no stored credential.
38
38
 
39
39
  ## When to Use
40
40
 
41
- 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.
41
+ Apply this rule when setting up a GitHub Actions workflow to deploy a Harper application using OIDC identity tokens instead of stored secrets. Use it when running `harper deploy setup=true provider=github-actions` for the first time, when writing or debugging a deploy workflow, or when managing trust policies, deploy users, and rolling restarts.
42
42
 
43
43
  ## How It Works
44
44
 
45
- ### One-Command Setup (branch-triggered deploys)
45
+ ### 1. Run one-command setup as a `super_user`
46
46
 
47
- 1. **Run setup once** from the project's checkout, signed in as a `super_user`:
47
+ Log in to the cluster, then run setup from the project's checkout:
48
48
 
49
- ```bash
50
- harper deploy setup=true provider=github-actions project=my-app
51
- ```
52
-
53
- If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=`:
54
-
55
- ```bash
56
- harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
57
- ```
58
-
59
- 2. **Understand what setup does** — it executes these steps automatically:
60
- - 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`.
61
- - 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.
62
- - 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>`.
63
- - Reads the policy back and compares it claim by claim.
64
- - Sets the repository's `HARPER_CLI_TARGET` variable via `gh` if one does not already exist.
65
-
66
- 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:
49
+ ```bash
50
+ harper login https://my-cluster.example.com:9925
51
+ harper deploy setup=true provider=github-actions project=my-app
52
+ ```
67
53
 
68
- ```bash
69
- harper drop_oidc_trust id=github-actions-<project>
70
- ```
54
+ If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=` explicitly — the policy pins the exact filename, and runs of a differently named workflow will never match:
71
55
 
72
- Then run setup again.
56
+ ```bash
57
+ harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
58
+ ```
73
59
 
74
- ---
60
+ Setup performs these steps automatically:
75
61
 
76
- ### Manual Setup (tag-triggered deploys)
62
+ 1. Resolves the GitHub repository's numeric id and canonical name from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` for private repositories without `gh`.
63
+ 2. Validates the workflow file: it must be able to run on `main` (or `branch=`), run a job in the `production` environment (`environment=`), and grant `permissions: id-token: write`. Setup stops before writing anything if the workflow could never match or never request a token.
64
+ 3. 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>`.
65
+ 4. Reads the policy back and compares it claim by claim with what it intended to write.
66
+ 5. Sets the repository's `HARPER_CLI_TARGET` variable via `gh` if one does not already exist.
77
67
 
78
- Use this path when the workflow deploys on version tags, because a branch pin cannot match a tag ref.
68
+ ### 2. Understand what setup creates
79
69
 
80
- 1. **Log in as `super_user`**:
70
+ | Object | Name | Purpose |
71
+ | ------------- | -------------------------- | ------------------------------------ |
72
+ | Role + user | `<project>-ci-deploy` | Privilege boundary for CI runs |
73
+ | Trust policy | `github-actions-<project>` | Maps OIDC claims to the deploy user |
74
+ | Repo variable | `HARPER_CLI_TARGET` | Points every workflow at the cluster |
81
75
 
82
- ```bash
83
- harper login https://my-cluster.example.com:9925
84
- ```
76
+ The policy's `audience` is the target URL with its port and a **trailing slash** (e.g. `https://my-cluster.example.com:9925/`). The claims include `repository_id`, `workflow_ref`, and `environment`.
85
77
 
86
- 2. **Create a deploy-only role and user** named `<project>-ci-deploy`:
78
+ ### 3. Create a deploy-only user manually (alternative to setup)
87
79
 
88
- ```bash
89
- harper add_role role=ci_deploy permission='{"operations":["deploy_component","get_job","get_deployment","registration_info"]}'
90
- harper add_user username=ci-deploy role=ci_deploy active=true password="$(openssl rand -base64 32)"
91
- ```
80
+ If you need to configure manually — for example, for a tag-triggered workflow that cannot use a branch pin — create the role and user yourself:
92
81
 
93
- - `deploy_component` — the deploy itself.
94
- - `get_deployment` — required for `harper deploy restart=rolling` to wait on every node; without it that wait fails with `403`.
95
- - `get_job` — required for the wait step; without it the wait step fails with `403`.
96
- - `registration_info` — version check before upload; omitting it logs a refused operation on every run.
97
- - `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.
82
+ ```bash
83
+ harper add_role role=ci_deploy permission='{"operations":["deploy_component","get_job","get_deployment","registration_info"]}'
84
+ harper add_user username=ci-deploy role=ci_deploy active=true password="$(openssl rand -base64 32)"
85
+ ```
98
86
 
99
- 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):
87
+ - **`deploy_component`** — the deploy itself.
88
+ - **`get_deployment`** — required for `harper deploy restart=rolling` to wait on every node; without it the wait fails with `403`.
89
+ - **`get_job`** — required for the wait step that polls `restartJobId`; without it the wait fails with `403`.
90
+ - **`registration_info`** — version check before upload; without it the deploy still works but logs a refused operation.
91
+ - **`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.
100
92
 
101
- ```bash
102
- harper add_oidc_trust \
103
- id=my-app-release \
104
- issuer=https://token.actions.githubusercontent.com \
105
- audience=https://my-cluster.example.com:9925/ \
106
- user=ci-deploy \
107
- claims='{"repository_id":"67890","workflow_path":"my-org/my-app/.github/workflows/deploy.yml","environment":"production"}'
108
- ```
93
+ ### 4. Add a trust policy manually (tag-triggered workflows)
109
94
 
110
- Key claim rules:
111
- - `repository_id` is immutable and survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
112
- - `workflow_path` is derived from `workflow_ref` by removing the `@<ref>` suffix; format is `<owner>/<repo>/<path>`.
113
- - `environment` is the ref gate. Without it, anyone who can push a branch can mint a token.
114
- - `audience` must be the exact target URL with its port and a **trailing slash**.
115
- - 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.
95
+ Tag-triggered workflows cannot pin `workflow_ref` because the tag is unknown at policy-write time. Pin `workflow_path` and gate on `environment` instead:
116
96
 
117
- 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.
97
+ ```bash
98
+ harper add_oidc_trust \
99
+ id=my-app-release \
100
+ issuer=https://token.actions.githubusercontent.com \
101
+ audience=https://my-cluster.example.com:9925/ \
102
+ user=ci-deploy \
103
+ claims='{"repository_id":"67890","workflow_path":"my-org/my-app/.github/workflows/deploy.yml","environment":"production"}'
104
+ ```
118
105
 
119
- 5. **Store the target as a repository variable** (not a secret):
106
+ - **`repository_id`** — immutable; survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
107
+ - **`workflow_path`** — Harper derives it from `workflow_ref` by removing the `@<ref>` suffix; format is `<owner>/<repo>/<path>`.
108
+ - **`environment`** — the ref gate. Without one, anyone who can push a branch could run the pinned workflow on it and mint a token. In the repository's **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern.
109
+ - **`audience`** — must be the exact target URL with port and **trailing slash**.
110
+ - **`workflow_ref`** pins workflow and ref together. Use for branch-triggered deploys, e.g. `my-org/my-app/.github/workflows/deploy.yml@refs/heads/main`.
120
111
 
121
- ```bash
122
- gh variable set HARPER_CLI_TARGET --repo my-org/my-app --body https://my-cluster.example.com:9925/
123
- ```
112
+ Store the target as a repository variable (not a secret):
124
113
 
125
- ---
114
+ ```bash
115
+ gh variable set HARPER_CLI_TARGET --repo my-org/my-app --body https://my-cluster.example.com:9925/
116
+ ```
126
117
 
127
- ### How OIDC Authentication Works in the Workflow
118
+ ### 5. Configure the workflow job for OIDC
128
119
 
129
- A job authenticates automatically when all four conditions hold:
120
+ Every `harper` command in the job authenticates through the trust policy automatically when all four conditions hold:
130
121
 
131
- 1. **The job declares `permissions: id-token: write`.**
132
- 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.
133
- 3. **The run matches the policy's claims**: its `repository_id`, `workflow_path`/`workflow_ref`, and `environment`.
122
+ 1. The job declares `id-token: write`.
123
+ 2. `HARPER_CLI_TARGET` equals the policy's `audience` (with port and trailing slash).
124
+ 3. The run matches the policy's claims (repository, workflow file, branch/environment).
134
125
  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.
135
126
 
136
- Nothing in the workflow names the policy. Every `harper` command in the job (`harper deploy`, `harper get_job`, etc.) authenticates through it automatically.
127
+ 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 failing.
137
128
 
138
- 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.
129
+ ### 6. Store a durable credential for private sources
139
130
 
140
- ---
141
-
142
- ### Policy Specificity for GitHub Actions
143
-
144
- For `issuer=https://token.actions.githubusercontent.com`, every policy must satisfy all three requirements:
131
+ Skip this step if your repository is public or your package is on a public registry.
145
132
 
146
- | Requirement | Satisfied by one of | Left open otherwise |
147
- | ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
148
- | **Pin the repository** | `repository_id`, `repository` | Any repository |
149
- | **Pin the workflow** | `workflow_ref`, `workflow_path`, `job_workflow_ref`, `job_workflow_path` | Any workflow in that repository |
150
- | **Gate the ref** | `workflow_ref`, `ref`, `environment` | Any branch that can be pushed to the repository |
133
+ For a private repository (git-tag deploys), store a fine-grained personal access token with **Contents: read-only** scoped to the application repository:
151
134
 
152
- Additional constraints:
153
-
154
- - `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`.
155
-
156
- ---
157
-
158
- ### Diagnosing a Rejected Exchange
159
-
160
- Run `list_oidc_trust` (requires `super_user`) to list all policies including disabled ones:
161
-
162
- ```json
163
- { "operation": "list_oidc_trust" }
135
+ ```bash
136
+ harper deploy setup=true provider=github project=my-app
164
137
  ```
165
138
 
166
- `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.
167
-
168
- Check the instance's `oidc-trust` log for server-side detail.
169
-
170
- ---
171
-
172
- ### Revoking Pipeline Access
173
-
174
- - **Stop future runs** — drop the policy:
175
-
176
- ```bash
177
- harper drop_oidc_trust id=github-actions-<project>
178
- ```
179
-
180
- This does not revoke tokens already issued (they are stateless JWTs valid for one hour).
181
-
182
- - **Stop a token already in circulation** — deactivate the user:
183
-
184
- ```bash
185
- harper alter_user username=<project>-ci-deploy active=false
186
- ```
187
-
188
- Use both together when responding to a suspected compromise.
189
-
190
- ---
191
-
192
- ### Providing a Durable Credential for a Private Source
193
-
194
- 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:
195
-
196
- - For a private repository: a fine-grained personal access token with **Contents: read-only** scoped to the application repository.
197
- - For GitHub Packages: a token with the `read:packages` scope.
198
-
199
- Store it in Harper once from your machine:
139
+ For GitHub Packages, store a durable token with the `read:packages` scope:
200
140
 
201
141
  ```bash
202
- # Private git repository
203
- harper deploy setup=true provider=github project=my-app
204
-
205
- # GitHub Packages
206
142
  harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
207
143
  ```
208
144
 
209
- 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.
145
+ 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. The workflows reference it by that name — the token never appears in the pipeline.
210
146
 
211
- ## Examples
147
+ ### 7. Write the deploy workflow
212
148
 
213
- ### Path A: Deploy a Tagged Release (`v1.2.3`) from the Repository
149
+ **Path A — deploy a tagged release (`v1.2.3`) from the repository:**
214
150
 
215
- 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.
151
+ 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. Pass `ref=<sha>` with the full commit SHA to deploy a different commit. If the repository needs a build step to be runnable, use Path B instead — do not reach for `install_allow_scripts`.
216
152
 
217
153
  ```yaml
218
154
  # .github/workflows/deploy.yml
@@ -231,12 +167,12 @@ jobs:
231
167
  env:
232
168
  HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
233
169
  steps:
234
- - uses: actions/checkout@v4
170
+ - uses: actions/checkout@v7
235
171
  with:
236
172
  persist-credentials: false
237
- - uses: actions/setup-node@v4
173
+ - uses: actions/setup-node@v7
238
174
  with:
239
- node-version: 22
175
+ node-version: 26
240
176
  - run: npm install --global harper@^5.3
241
177
  - name: Deploy the tagged commit
242
178
  run: harper deploy project=my-app by_ref=true restart=rolling json=true > deploy.json
@@ -261,22 +197,19 @@ jobs:
261
197
  exit 1
262
198
  ```
263
199
 
264
- Key details:
265
-
266
- - **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.
267
- - **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`, where `actions/checkout` otherwise leaves it for every later step.
268
- - **`harper@^5.3`** pins the CLI's major version. 5.3 is the first CLI that authenticates with the identity token.
269
- - **`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.
270
- - **`restart=rolling`** restarts nodes one at a time so the cluster keeps serving throughout. Use `restart=true` for a single-node or dev instance.
271
- - **`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.
272
- - **`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`.
273
- - **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`.
274
-
275
200
  For a private repository, add `credential=true` to the deploy command.
276
201
 
277
- ---
202
+ Key details for Path A:
278
203
 
279
- ### Path B: Build in CI, Publish to GitHub Packages, Deploy the Artifact
204
+ - **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`, where `actions/checkout` otherwise leaves it for every later step. From v6 it saves the token in a file under `$RUNNER_TEMP` rather than in `.git/config`, which `harper deploy` uploads with the checkout, but later steps can still read it.
205
+ - **`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.
206
+ - **`restart=rolling`** restarts nodes one at a time. `restart=true` deploys to every node at once; each node replaces its workers a few at a time while the others keep serving.
207
+ - **`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; when it is `unavailable`, the certified wait is skipped.
208
+ - **`json=true`** prints the deploy result as JSON on stdout. Progress and authentication messages go to stderr.
209
+ - **Waiting for every node**: with `restart=rolling` on v5.4.0 and later, unless `certification` is `unavailable`, `harper deploy` waits for every node on the deployment record before it exits. Its result then carries `rollout`, and the wait step does nothing. Otherwise the wait step polls `restartJobId` with `get_job` until `COMPLETE` or `ERROR`, retrying polls that fail (such as one that reaches a node while it restarts). It gives up after 60 polls (~10 minutes).
210
+ - **The job lives on one node.** Harper does not replicate jobs, so only the node that received the deploy knows the rolling job. Through a **load-balanced** cluster URL, at least one poll must reach that node. Routing that sends polls to a different node than the deploy causes the step to fail, saying the job was not on the node that answered and its outcome is unknown. If your load balancer routes that way, use one node's own URL for both the deploy and the wait, and as the trust policy's `audience`.
211
+
212
+ **Path B — build in CI, publish to GitHub Packages, deploy the artifact:**
280
213
 
281
214
  Give `package.json` a scoped name and `"publishConfig": { "registry": "https://npm.pkg.github.com" }`:
282
215
 
@@ -305,12 +238,12 @@ jobs:
305
238
  contents: read
306
239
  packages: write
307
240
  steps:
308
- - uses: actions/checkout@v4
241
+ - uses: actions/checkout@v7
309
242
  with:
310
243
  persist-credentials: false
311
- - uses: actions/setup-node@v4
244
+ - uses: actions/setup-node@v7
312
245
  with:
313
- node-version: 22
246
+ node-version: 26
314
247
  registry-url: https://npm.pkg.github.com
315
248
  scope: '@my-org'
316
249
  - run: npm ci
@@ -332,9 +265,9 @@ jobs:
332
265
  env:
333
266
  HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
334
267
  steps:
335
- - uses: actions/setup-node@v4
268
+ - uses: actions/setup-node@v7
336
269
  with:
337
- node-version: 22
270
+ node-version: 26
338
271
  - run: npm install --global harper@^5.3
339
272
  - name: Deploy the published version
340
273
  run: |
@@ -361,26 +294,86 @@ jobs:
361
294
  exit 1
362
295
  ```
363
296
 
364
- 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.
297
+ The workflow has two jobs so the job that can request an identity token runs none of your code:
365
298
 
366
- ---
299
+ - **`publish`** installs, builds, tests, and publishes with `contents: read` and `packages: write` only. It cannot request an identity token.
300
+ - **`deploy`** runs once `publish` has finished (`needs: publish`), holds the `production` environment and `id-token: write`, installs only the Harper CLI, then deploys the published version.
301
+
302
+ ### 8. Manage trust policies
303
+
304
+ **List all policies** (including disabled ones) — `super_user` only:
367
305
 
368
- ### Checking the Deployment Record
306
+ ```bash
307
+ harper list_oidc_trust
308
+ ```
309
+
310
+ Returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, `invalid_reason`, and `exchangeable`. Check `invalid_reason` first when diagnosing a rejected exchange — the exchange itself does not report which check failed. Diagnose further with the instance's `oidc-trust` log.
311
+
312
+ **Drop a policy** to stop future runs from exchanging — `super_user` only:
313
+
314
+ ```bash
315
+ harper drop_oidc_trust id=github-actions-<project>
316
+ ```
317
+
318
+ Fails with `404` if no policy has that `id`. Does not revoke already-issued tokens (valid for one hour). To also stop a token already in circulation, deactivate the user:
319
+
320
+ ```bash
321
+ harper alter_user username=<project>-ci-deploy active=false
322
+ ```
323
+
324
+ **Replace a policy**: drop it with `harper drop_oidc_trust id=github-actions-<project>`, then run setup again. Setup never overwrites an existing policy.
325
+
326
+ ## Examples
327
+
328
+ **Minimal OIDC-authenticated deploy job (branch-triggered, setup already run):**
329
+
330
+ ```yaml
331
+ deploy:
332
+ runs-on: ubuntu-latest
333
+ environment: production
334
+ permissions:
335
+ contents: read
336
+ id-token: write
337
+ env:
338
+ HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
339
+ steps:
340
+ - uses: actions/checkout@v7
341
+ with:
342
+ persist-credentials: false
343
+ - run: npm install --global harper@^5.3
344
+ - run: harper deploy project=my-app restart=rolling
345
+ ```
346
+
347
+ **Check the deployment record after a deploy:**
369
348
 
370
349
  ```bash
371
350
  harper get_deployment deployment_id="$(jq -r .deployment_id deploy.json)" json=true
372
351
  ```
373
352
 
374
- Use `list_deployments` to see the history of what was deployed and when, and filter by commit with `sha`.
353
+ **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`. Use `list_deployments` to see the history of what was deployed and when, and filter by commit with `sha`.
354
+
355
+ **Revoke pipeline access:**
375
356
 
376
- - **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.
357
+ ```bash
358
+ harper drop_oidc_trust id=github-actions-<project>
359
+ harper alter_user username=<project>-ci-deploy active=false
360
+ ```
377
361
 
378
362
  ## Notes
379
363
 
380
- - `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.
381
- - `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.
382
- - `list_oidc_trust`, `drop_oidc_trust`, and `alter_user` all require `super_user`.
383
- - `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.
384
- - `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.
385
- - 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.
386
- - See [deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) for cluster-level deployment context.
364
+ - The `audience` in every trust policy and in `HARPER_CLI_TARGET` must include the port and a **trailing slash** — `https://my-cluster.example.com:9925/`. A missing trailing slash causes the exchange to fail.
365
+ - `HARPER_CLI_REFRESH_TOKEN` and any other stored credential outrank the OIDC exchange. Remove them from the workflow if you are switching to OIDC.
366
+ - `harper@^5.3` pins the CLI major version. 5.3 is the first version that authenticates with an identity token.
367
+ - `runs-on: ubuntu-latest` is used in all example workflows. The git-credential helper for private repositories requires git ≥ 2.31 and is not supported on Windows nodes.
368
+ - Policy specificity for `https://token.actions.githubusercontent.com` requires all three of:
369
+
370
+ | Requirement | Satisfied by one of | Left open otherwise |
371
+ | ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
372
+ | **Pin the repository** | `repository_id`, `repository` | Any repository |
373
+ | **Pin the workflow** | `workflow_ref`, `workflow_path`, `job_workflow_ref`, `job_workflow_path` | Any workflow in that repository |
374
+ | **Gate the ref** | `workflow_ref`, `ref`, `environment` | Any branch that can be pushed to the repository |
375
+
376
+ - `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`.
377
+ - Two `exchangeable` policies that can match the same runs but give them a different user or operations cause the exchange to refuse those runs. Both will carry `invalid_reason`. Drop or disable one, or give them non-overlapping claims.
378
+ - `add_oidc_trust` replaces a policy with the same `id`. Setup checks for conflicts immediately before writing, but a policy created by another `super_user` in that instant could still be overwritten.
379
+ - See [deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) for cluster-level deployment configuration on Harper Fabric.