@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.
- package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
- package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/.agents/skills/harper-mcp/AGENTS.md +228 -155
- package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
- package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/agent/skills/harper-mcp/AGENTS.md +228 -155
- package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/package.json +1 -1
- 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:
|
|
32
|
-
inputHash:
|
|
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
|
|
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
|
|
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
|
-
###
|
|
45
|
+
### 1. Run one-command setup as a `super_user`
|
|
46
46
|
|
|
47
|
-
|
|
47
|
+
Log in to the cluster, then run setup from the project's checkout:
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
68
|
+
### 2. Understand what setup creates
|
|
79
69
|
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
78
|
+
### 3. Create a deploy-only user manually (alternative to setup)
|
|
87
79
|
|
|
88
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
118
|
+
### 5. Configure the workflow job for OIDC
|
|
128
119
|
|
|
129
|
-
|
|
120
|
+
Every `harper` command in the job authenticates through the trust policy automatically when all four conditions hold:
|
|
130
121
|
|
|
131
|
-
1.
|
|
132
|
-
2.
|
|
133
|
-
3.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
147
|
+
### 7. Write the deploy workflow
|
|
212
148
|
|
|
213
|
-
|
|
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
|
|
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@
|
|
170
|
+
- uses: actions/checkout@v7
|
|
235
171
|
with:
|
|
236
172
|
persist-credentials: false
|
|
237
|
-
- uses: actions/setup-node@
|
|
173
|
+
- uses: actions/setup-node@v7
|
|
238
174
|
with:
|
|
239
|
-
node-version:
|
|
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
|
-
|
|
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@
|
|
241
|
+
- uses: actions/checkout@v7
|
|
309
242
|
with:
|
|
310
243
|
persist-credentials: false
|
|
311
|
-
- uses: actions/setup-node@
|
|
244
|
+
- uses: actions/setup-node@v7
|
|
312
245
|
with:
|
|
313
|
-
node-version:
|
|
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@
|
|
268
|
+
- uses: actions/setup-node@v7
|
|
336
269
|
with:
|
|
337
|
-
node-version:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 `
|
|
381
|
-
- `HARPER_CLI_REFRESH_TOKEN` and any other
|
|
382
|
-
- `
|
|
383
|
-
- `
|
|
384
|
-
-
|
|
385
|
-
|
|
386
|
-
|
|
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.
|