create-harper 1.13.7 → 1.14.1

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 (48) hide show
  1. package/README.md +10 -2
  2. package/lib/constants/helpMessage.js +4 -0
  3. package/lib/steps/installAndOptionallyStart.js +13 -1
  4. package/package.json +3 -2
  5. package/template-nextjs/README.md +11 -7
  6. package/template-nextjs/_github/workflows/deploy.yaml +11 -49
  7. package/template-nextjs-ts/README.md +11 -7
  8. package/template-nextjs-ts/_github/workflows/deploy.yaml +11 -49
  9. package/template-react/README.md +28 -7
  10. package/template-react/_github/workflows/deploy.yaml +11 -49
  11. package/template-react/_github/workflows/preview.yaml +54 -0
  12. package/template-react/package.json +2 -1
  13. package/template-react-ssr/README.md +28 -7
  14. package/template-react-ssr/_github/workflows/deploy.yaml +11 -49
  15. package/template-react-ssr/_github/workflows/preview.yaml +54 -0
  16. package/template-react-ssr/package.json +2 -1
  17. package/template-react-ts/README.md +28 -7
  18. package/template-react-ts/_github/workflows/deploy.yaml +11 -49
  19. package/template-react-ts/_github/workflows/preview.yaml +54 -0
  20. package/template-react-ts/package.json +2 -1
  21. package/template-react-ts-ssr/README.md +28 -7
  22. package/template-react-ts-ssr/_github/workflows/deploy.yaml +11 -49
  23. package/template-react-ts-ssr/_github/workflows/preview.yaml +54 -0
  24. package/template-react-ts-ssr/package.json +2 -1
  25. package/template-vanilla/README.md +28 -7
  26. package/template-vanilla/_github/workflows/deploy.yaml +11 -49
  27. package/template-vanilla/_github/workflows/preview.yaml +54 -0
  28. package/template-vanilla/package.json +2 -1
  29. package/template-vanilla-ts/README.md +28 -7
  30. package/template-vanilla-ts/_github/workflows/deploy.yaml +11 -49
  31. package/template-vanilla-ts/_github/workflows/preview.yaml +54 -0
  32. package/template-vanilla-ts/package.json +2 -1
  33. package/template-vue/README.md +28 -7
  34. package/template-vue/_github/workflows/deploy.yaml +11 -49
  35. package/template-vue/_github/workflows/preview.yaml +54 -0
  36. package/template-vue/package.json +2 -1
  37. package/template-vue-ssr/README.md +28 -7
  38. package/template-vue-ssr/_github/workflows/deploy.yaml +11 -49
  39. package/template-vue-ssr/_github/workflows/preview.yaml +54 -0
  40. package/template-vue-ssr/package.json +2 -1
  41. package/template-vue-ts/README.md +28 -7
  42. package/template-vue-ts/_github/workflows/deploy.yaml +11 -49
  43. package/template-vue-ts/_github/workflows/preview.yaml +54 -0
  44. package/template-vue-ts/package.json +2 -1
  45. package/template-vue-ts-ssr/README.md +28 -7
  46. package/template-vue-ts-ssr/_github/workflows/deploy.yaml +11 -49
  47. package/template-vue-ts-ssr/_github/workflows/preview.yaml +54 -0
  48. package/template-vue-ts-ssr/package.json +2 -1
@@ -113,13 +113,13 @@ harper login
113
113
 
114
114
  ### How the workflow authenticates
115
115
 
116
- The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
116
+ The workflow deploys with [`HarperFast/deploy-action`](https://github.com/HarperFast/deploy-action), which runs the `harper` CLI with no credentials on it. The CLI authenticates by itself, because:
117
117
 
118
118
  - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
119
- - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
119
+ - the `HARPER_CLI_TARGET` repository variable holds your cluster's URL, so the CLI asks for a token addressed to that cluster;
120
120
  - the cluster holds a **trust policy** that accepts tokens from this repository's `deploy.yaml`, on `main`, in the `production` environment, and lets them act as a deploy-only user.
121
121
 
122
- The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
122
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Install the CLI in that job and any `harper` command you add works the same way, without adding credentials.
123
123
 
124
124
  ### One-time setup
125
125
 
@@ -131,7 +131,7 @@ your-package-manager-run-here deploy:setup-ci
131
131
 
132
132
  It creates, on the cluster:
133
133
 
134
- - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
134
+ - a role that can run only `deploy_component`, `get_deployment` and `get_job` (to follow the rollout) and `registration_info` (the CLI's version check), and a user in it;
135
135
  - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
136
136
 
137
137
  With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_CLI_TARGET` repository variable; otherwise it prints the command to run. Running it again changes nothing. If something on the cluster already exists and differs, it stops and says what, without changing anything.
@@ -142,9 +142,9 @@ The deploy user can deploy any app on the cluster, so who can deploy comes down
142
142
 
143
143
  ### What a deploy does
144
144
 
145
- The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
145
+ The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, the run waits for every node, and each node first loads the release in a canary worker and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving. On an older cluster, the run passes as soon as the first node has the release.
146
146
 
147
- The run's summary names the deployment and its `certification`:
147
+ The deploy step's log names the deployment and its `certification`:
148
148
 
149
149
  - `certified`: the canary loaded the release.
150
150
  - `uncertified` or `unavailable`: the release went out without that check, for a reason the [deploy reference](https://docs.harperdb.io/reference/v5/operations-api/operations#certifying-a-release-in-a-canary-worker) lists.
@@ -168,6 +168,27 @@ your-package-manager-run-here deploy
168
168
 
169
169
  deploys this directory the same way, as the user you logged in with. It returns once the first node has the release; the response's `restartJobId` is the job that takes it to the others, which `harper get_job id=<restartJobId>` reports on.
170
170
 
171
+ ### Pull request previews
172
+
173
+ Turn these on and every pull request into `main` from a branch in this repository gets its own running copy of the app, at `https://<branch>.app.<your-cluster-host>/`, with its own branch of your databases. A comment on the pull request links to it. Each push updates it, and closing the pull request removes it; a preview that misses that expires after seven days.
174
+
175
+ The [preview workflow](./.github/workflows/preview.yaml) skips its jobs until you turn previews on. That takes Harper 5.4 or later on the cluster and on your machine. Run this once from the project, signed in as a super user:
176
+
177
+ ```sh
178
+ your-package-manager-run-here deploy:setup-previews
179
+ ```
180
+
181
+ It refuses a workflow with a job that runs for forks or checks out the pull request. Then it creates, on the cluster, a user that can only deploy and drop this app's previews, and trust policies for the workflow's `preview` and `preview-cleanup` environments. With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_PREVIEW_TARGET` repository variable, which is what turns the jobs on; otherwise it prints the command to run. To remove it all, previews included, run `harper preview teardown app=your-component-name-here`.
182
+
183
+ The workflow never checks out or builds a pull request. The cluster fetches the commit itself, then installs and builds it there. So anyone who can push a branch here, a bot included, can run code on your cluster, and Harper doesn't sandbox an app's code. A preview's writes stay in its own database branch, except in the `system` database (users and roles), which can't be branched.
184
+
185
+ - **Private repositories:** the cluster needs a credential to fetch each commit. Setup offers to seal one, and the workflow uses it whenever the repository is private.
186
+ - **Public repositories:** the workflow runs on `pull_request_target`, which [GitHub's default protection](https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target) blocks for affected public repositories from December 2, 2026. A blocked run fails with an error, even while previews are off. To allow it, go to **Settings → Actions → Policies**, create a policy with an active enforcement status that targets `.github/workflows/preview.yaml`, and add a **Restrict events** rule that allows `pull_request_target`. If you don't want previews, delete the workflow instead.
187
+ - **Forks:** pull requests from forks get no preview, and the cluster is never called for them.
188
+ - **Approvals:** to have a person approve each preview, add a required reviewer to the `preview` environment under **Settings → Environments**. Leave `preview-cleanup` without one, so closing a pull request never waits for an approval.
189
+
190
+ The [deploy action's documentation](https://github.com/HarperFast/deploy-action#pull-request-previews) covers the rest, such as using another domain and sweeping missed previews.
191
+
171
192
  ### When a run is refused
172
193
 
173
194
  If the deploy step fails with a 401, the cluster did not accept the run's token. `harper list_oidc_trust` shows each policy, and an `invalid_reason` when one can't match; the cluster's `oidc-trust` log says which check failed. Rerunning `your-package-manager-run-here deploy:setup-ci` reports a policy that no longer matches the workflow.
@@ -177,7 +198,7 @@ If the deploy step fails with a 401, the cluster did not accept the run's token.
177
198
  Projects created before this deployed on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and don't have this workflow or the `deploy:setup-ci` script. To move one over:
178
199
 
179
200
  1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
180
- 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
201
+ 2. Run the setup from the project, with the `app:` value the copied workflow passes to the deploy action: `harper deploy setup=true provider=github-actions project=<that value>`.
181
202
  3. Push the new workflow to `main`.
182
203
  4. Once nothing references it, delete the `HARPER_CLI_REFRESH_TOKEN` secret under **Settings → Secrets and variables → Actions**. The new workflow doesn't read it, so it is only a credential left lying around.
183
204
 
@@ -1,6 +1,6 @@
1
1
  # Tests every pull request, and deploys to your Harper cluster when a change merges to `main`. The
2
- # deploy job holds no Harper credential: its `harper` commands authenticate with GitHub's OIDC token
3
- # under a trust policy on the cluster. Set that up once with
2
+ # deploy job holds no Harper credential: HarperFast/deploy-action authenticates with GitHub's OIDC
3
+ # token under a trust policy on the cluster. Set that up once with
4
4
  # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README).
5
5
  name: Deploy to Harper
6
6
  on:
@@ -63,52 +63,14 @@ jobs:
63
63
  with:
64
64
  # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
65
65
  persist-credentials: false
66
- - name: Set up Node.js
67
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
68
- with:
69
- node-version-file: '.nvmrc'
70
- - name: Install Harper CLI
71
- # 5.3 is the first CLI that authenticates with the OIDC token.
72
- run: npm install --global harper@^5.3
73
- - name: Deploy
66
+ - name: Check the deploy target
67
+ # The action refuses an empty target too, but can't say which script sets it.
74
68
  run: |
75
- # With no target the CLI would fall back to a saved login or a local node, and succeed.
76
69
  [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
77
- harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
78
- - name: Wait for every node to take the release
79
- # The deploy returns once the node it reached has the release; the others take it in a job.
80
- run: |
81
- JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
82
- [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
83
- LAST="could not be read"
84
- for attempt in $(seq 60); do
85
- sleep 10
86
- harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
87
- case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
88
- COMPLETE) exit 0 ;;
89
- ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
90
- MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
91
- *) LAST="was still running" ;;
92
- esac
93
- done
94
- echo "::error::After 60 polls, job $JOB_ID $LAST"
95
- exit 1
96
- - name: Summarize
97
- if: ${{ !cancelled() }}
98
- env:
99
- JOB_STATUS: ${{ job.status }}
100
- run: |
101
- [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
102
- {
103
- if [ "$JOB_STATUS" = success ]; then
104
- echo "### Deployed your-component-name-here"
105
- elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
106
- echo "### Deploy of your-component-name-here did not complete on every node"
107
- else
108
- echo "### Deploy of your-component-name-here failed"
109
- fi
110
- jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
111
- echo ""
112
- echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
113
- echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
114
- } >> "$GITHUB_STEP_SUMMARY"
70
+ - name: Deploy
71
+ # From Harper 5.4 this waits for every node, and fails the run if a node's canary rejects the release.
72
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
73
+ with:
74
+ target: ${{ env.HARPER_CLI_TARGET }}
75
+ app: your-component-name-here
76
+ restart: rolling
@@ -0,0 +1,54 @@
1
+ # Gives each pull request its own copy of the app on your Harper cluster, and removes it when the
2
+ # pull request closes. Both jobs stay skipped until you turn previews on, once, with
3
+ # `your-package-manager-run-here deploy:setup-previews` (see "Pull request previews" in the README).
4
+ #
5
+ # `pull_request_target` runs this file as it is on the default branch, so a pull request can't change
6
+ # what runs with the preview identity. Keep it that way: never check out or build the pull request
7
+ # here. The cluster fetches the commit itself, and the pull request's code runs there.
8
+ name: Preview
9
+ on:
10
+ pull_request_target:
11
+ types: [opened, reopened, synchronize, closed]
12
+ branches: [main]
13
+
14
+ permissions: {}
15
+
16
+ jobs:
17
+ deploy:
18
+ # The head repository is in no claim of the identity token, so this is what keeps forks out.
19
+ if: vars.HARPER_PREVIEW_TARGET != '' && github.event.action != 'closed' && github.event.pull_request.head.repo.full_name == github.repository
20
+ runs-on: ubuntu-latest
21
+ environment: preview
22
+ permissions:
23
+ id-token: write
24
+ pull-requests: write
25
+ deployments: write
26
+ concurrency:
27
+ group: harper-preview-${{ github.event.pull_request.number }}
28
+ steps:
29
+ - name: Deploy the preview
30
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
31
+ with:
32
+ target: ${{ vars.HARPER_PREVIEW_TARGET }}
33
+ app: your-component-name-here
34
+ preview: true
35
+ # A private repository's commit takes the credential `deploy:setup-previews` offers to seal.
36
+ credential: ${{ github.event.repository.private }}
37
+
38
+ cleanup:
39
+ # Not in the deploy job's environment or concurrency group, so its required reviewers, or a deploy
40
+ # waiting for them, can't hold up removing a preview.
41
+ if: vars.HARPER_PREVIEW_TARGET != '' && github.event.action == 'closed' && github.event.pull_request.head.repo.full_name == github.repository
42
+ runs-on: ubuntu-latest
43
+ environment: preview-cleanup
44
+ permissions:
45
+ id-token: write
46
+ pull-requests: write
47
+ deployments: write
48
+ steps:
49
+ - name: Remove the preview
50
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
51
+ with:
52
+ target: ${{ vars.HARPER_PREVIEW_TARGET }}
53
+ app: your-component-name-here
54
+ preview: true
@@ -14,7 +14,8 @@
14
14
  "test:watch": "node --watch --test test/*.test.js",
15
15
  "build": "vite build",
16
16
  "deploy": "harper deploy project=your-component-name-here restart=rolling",
17
- "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here"
17
+ "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here",
18
+ "deploy:setup-previews": "harper preview setup app=your-component-name-here"
18
19
  },
19
20
  "dependencies": {
20
21
  "@harperfast/schema-codegen": "^2.0.0",
@@ -121,13 +121,13 @@ harper login
121
121
 
122
122
  ### How the workflow authenticates
123
123
 
124
- The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
124
+ The workflow deploys with [`HarperFast/deploy-action`](https://github.com/HarperFast/deploy-action), which runs the `harper` CLI with no credentials on it. The CLI authenticates by itself, because:
125
125
 
126
126
  - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
127
- - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
127
+ - the `HARPER_CLI_TARGET` repository variable holds your cluster's URL, so the CLI asks for a token addressed to that cluster;
128
128
  - the cluster holds a **trust policy** that accepts tokens from this repository's `deploy.yaml`, on `main`, in the `production` environment, and lets them act as a deploy-only user.
129
129
 
130
- The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
130
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Install the CLI in that job and any `harper` command you add works the same way, without adding credentials.
131
131
 
132
132
  ### One-time setup
133
133
 
@@ -139,7 +139,7 @@ your-package-manager-run-here deploy:setup-ci
139
139
 
140
140
  It creates, on the cluster:
141
141
 
142
- - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
142
+ - a role that can run only `deploy_component`, `get_deployment` and `get_job` (to follow the rollout) and `registration_info` (the CLI's version check), and a user in it;
143
143
  - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
144
144
 
145
145
  With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_CLI_TARGET` repository variable; otherwise it prints the command to run. Running it again changes nothing. If something on the cluster already exists and differs, it stops and says what, without changing anything.
@@ -150,9 +150,9 @@ The deploy user can deploy any app on the cluster, so who can deploy comes down
150
150
 
151
151
  ### What a deploy does
152
152
 
153
- The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
153
+ The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, the run waits for every node, and each node first loads the release in a canary worker and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving. On an older cluster, the run passes as soon as the first node has the release.
154
154
 
155
- The run's summary names the deployment and its `certification`:
155
+ The deploy step's log names the deployment and its `certification`:
156
156
 
157
157
  - `certified`: the canary loaded the release.
158
158
  - `uncertified` or `unavailable`: the release went out without that check, for a reason the [deploy reference](https://docs.harperdb.io/reference/v5/operations-api/operations#certifying-a-release-in-a-canary-worker) lists.
@@ -176,6 +176,27 @@ your-package-manager-run-here deploy
176
176
 
177
177
  deploys this directory the same way, as the user you logged in with. It returns once the first node has the release; the response's `restartJobId` is the job that takes it to the others, which `harper get_job id=<restartJobId>` reports on.
178
178
 
179
+ ### Pull request previews
180
+
181
+ Turn these on and every pull request into `main` from a branch in this repository gets its own running copy of the app, at `https://<branch>.app.<your-cluster-host>/`, with its own branch of your databases. A comment on the pull request links to it. Each push updates it, and closing the pull request removes it; a preview that misses that expires after seven days.
182
+
183
+ The [preview workflow](./.github/workflows/preview.yaml) skips its jobs until you turn previews on. That takes Harper 5.4 or later on the cluster and on your machine. Run this once from the project, signed in as a super user:
184
+
185
+ ```sh
186
+ your-package-manager-run-here deploy:setup-previews
187
+ ```
188
+
189
+ It refuses a workflow with a job that runs for forks or checks out the pull request. Then it creates, on the cluster, a user that can only deploy and drop this app's previews, and trust policies for the workflow's `preview` and `preview-cleanup` environments. With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_PREVIEW_TARGET` repository variable, which is what turns the jobs on; otherwise it prints the command to run. To remove it all, previews included, run `harper preview teardown app=your-component-name-here`.
190
+
191
+ The workflow never checks out or builds a pull request. The cluster fetches the commit itself, then installs and builds it there. So anyone who can push a branch here, a bot included, can run code on your cluster, and Harper doesn't sandbox an app's code. A preview's writes stay in its own database branch, except in the `system` database (users and roles), which can't be branched.
192
+
193
+ - **Private repositories:** the cluster needs a credential to fetch each commit. Setup offers to seal one, and the workflow uses it whenever the repository is private.
194
+ - **Public repositories:** the workflow runs on `pull_request_target`, which [GitHub's default protection](https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target) blocks for affected public repositories from December 2, 2026. A blocked run fails with an error, even while previews are off. To allow it, go to **Settings → Actions → Policies**, create a policy with an active enforcement status that targets `.github/workflows/preview.yaml`, and add a **Restrict events** rule that allows `pull_request_target`. If you don't want previews, delete the workflow instead.
195
+ - **Forks:** pull requests from forks get no preview, and the cluster is never called for them.
196
+ - **Approvals:** to have a person approve each preview, add a required reviewer to the `preview` environment under **Settings → Environments**. Leave `preview-cleanup` without one, so closing a pull request never waits for an approval.
197
+
198
+ The [deploy action's documentation](https://github.com/HarperFast/deploy-action#pull-request-previews) covers the rest, such as using another domain and sweeping missed previews.
199
+
179
200
  ### When a run is refused
180
201
 
181
202
  If the deploy step fails with a 401, the cluster did not accept the run's token. `harper list_oidc_trust` shows each policy, and an `invalid_reason` when one can't match; the cluster's `oidc-trust` log says which check failed. Rerunning `your-package-manager-run-here deploy:setup-ci` reports a policy that no longer matches the workflow.
@@ -185,7 +206,7 @@ If the deploy step fails with a 401, the cluster did not accept the run's token.
185
206
  Projects created before this deployed on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and don't have this workflow or the `deploy:setup-ci` script. To move one over:
186
207
 
187
208
  1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
188
- 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
209
+ 2. Run the setup from the project, with the `app:` value the copied workflow passes to the deploy action: `harper deploy setup=true provider=github-actions project=<that value>`.
189
210
  3. Push the new workflow to `main`.
190
211
  4. Once nothing references it, delete the `HARPER_CLI_REFRESH_TOKEN` secret under **Settings → Secrets and variables → Actions**. The new workflow doesn't read it, so it is only a credential left lying around.
191
212
 
@@ -1,6 +1,6 @@
1
1
  # Tests every pull request, and deploys to your Harper cluster when a change merges to `main`. The
2
- # deploy job holds no Harper credential: its `harper` commands authenticate with GitHub's OIDC token
3
- # under a trust policy on the cluster. Set that up once with
2
+ # deploy job holds no Harper credential: HarperFast/deploy-action authenticates with GitHub's OIDC
3
+ # token under a trust policy on the cluster. Set that up once with
4
4
  # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README).
5
5
  name: Deploy to Harper
6
6
  on:
@@ -63,52 +63,14 @@ jobs:
63
63
  with:
64
64
  # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
65
65
  persist-credentials: false
66
- - name: Set up Node.js
67
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
68
- with:
69
- node-version-file: '.nvmrc'
70
- - name: Install Harper CLI
71
- # 5.3 is the first CLI that authenticates with the OIDC token.
72
- run: npm install --global harper@^5.3
73
- - name: Deploy
66
+ - name: Check the deploy target
67
+ # The action refuses an empty target too, but can't say which script sets it.
74
68
  run: |
75
- # With no target the CLI would fall back to a saved login or a local node, and succeed.
76
69
  [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
77
- harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
78
- - name: Wait for every node to take the release
79
- # The deploy returns once the node it reached has the release; the others take it in a job.
80
- run: |
81
- JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
82
- [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
83
- LAST="could not be read"
84
- for attempt in $(seq 60); do
85
- sleep 10
86
- harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
87
- case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
88
- COMPLETE) exit 0 ;;
89
- ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
90
- MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
91
- *) LAST="was still running" ;;
92
- esac
93
- done
94
- echo "::error::After 60 polls, job $JOB_ID $LAST"
95
- exit 1
96
- - name: Summarize
97
- if: ${{ !cancelled() }}
98
- env:
99
- JOB_STATUS: ${{ job.status }}
100
- run: |
101
- [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
102
- {
103
- if [ "$JOB_STATUS" = success ]; then
104
- echo "### Deployed your-component-name-here"
105
- elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
106
- echo "### Deploy of your-component-name-here did not complete on every node"
107
- else
108
- echo "### Deploy of your-component-name-here failed"
109
- fi
110
- jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
111
- echo ""
112
- echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
113
- echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
114
- } >> "$GITHUB_STEP_SUMMARY"
70
+ - name: Deploy
71
+ # From Harper 5.4 this waits for every node, and fails the run if a node's canary rejects the release.
72
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
73
+ with:
74
+ target: ${{ env.HARPER_CLI_TARGET }}
75
+ app: your-component-name-here
76
+ restart: rolling
@@ -0,0 +1,54 @@
1
+ # Gives each pull request its own copy of the app on your Harper cluster, and removes it when the
2
+ # pull request closes. Both jobs stay skipped until you turn previews on, once, with
3
+ # `your-package-manager-run-here deploy:setup-previews` (see "Pull request previews" in the README).
4
+ #
5
+ # `pull_request_target` runs this file as it is on the default branch, so a pull request can't change
6
+ # what runs with the preview identity. Keep it that way: never check out or build the pull request
7
+ # here. The cluster fetches the commit itself, and the pull request's code runs there.
8
+ name: Preview
9
+ on:
10
+ pull_request_target:
11
+ types: [opened, reopened, synchronize, closed]
12
+ branches: [main]
13
+
14
+ permissions: {}
15
+
16
+ jobs:
17
+ deploy:
18
+ # The head repository is in no claim of the identity token, so this is what keeps forks out.
19
+ if: vars.HARPER_PREVIEW_TARGET != '' && github.event.action != 'closed' && github.event.pull_request.head.repo.full_name == github.repository
20
+ runs-on: ubuntu-latest
21
+ environment: preview
22
+ permissions:
23
+ id-token: write
24
+ pull-requests: write
25
+ deployments: write
26
+ concurrency:
27
+ group: harper-preview-${{ github.event.pull_request.number }}
28
+ steps:
29
+ - name: Deploy the preview
30
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
31
+ with:
32
+ target: ${{ vars.HARPER_PREVIEW_TARGET }}
33
+ app: your-component-name-here
34
+ preview: true
35
+ # A private repository's commit takes the credential `deploy:setup-previews` offers to seal.
36
+ credential: ${{ github.event.repository.private }}
37
+
38
+ cleanup:
39
+ # Not in the deploy job's environment or concurrency group, so its required reviewers, or a deploy
40
+ # waiting for them, can't hold up removing a preview.
41
+ if: vars.HARPER_PREVIEW_TARGET != '' && github.event.action == 'closed' && github.event.pull_request.head.repo.full_name == github.repository
42
+ runs-on: ubuntu-latest
43
+ environment: preview-cleanup
44
+ permissions:
45
+ id-token: write
46
+ pull-requests: write
47
+ deployments: write
48
+ steps:
49
+ - name: Remove the preview
50
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
51
+ with:
52
+ target: ${{ vars.HARPER_PREVIEW_TARGET }}
53
+ app: your-component-name-here
54
+ preview: true
@@ -14,7 +14,8 @@
14
14
  "test:watch": "node --watch --test test/*.test.ts",
15
15
  "build": "vite build",
16
16
  "deploy": "harper deploy project=your-component-name-here restart=rolling",
17
- "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here"
17
+ "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here",
18
+ "deploy:setup-previews": "harper preview setup app=your-component-name-here"
18
19
  },
19
20
  "dependencies": {
20
21
  "@harperfast/schema-codegen": "^2.0.0",
@@ -121,13 +121,13 @@ harper login
121
121
 
122
122
  ### How the workflow authenticates
123
123
 
124
- The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
124
+ The workflow deploys with [`HarperFast/deploy-action`](https://github.com/HarperFast/deploy-action), which runs the `harper` CLI with no credentials on it. The CLI authenticates by itself, because:
125
125
 
126
126
  - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
127
- - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
127
+ - the `HARPER_CLI_TARGET` repository variable holds your cluster's URL, so the CLI asks for a token addressed to that cluster;
128
128
  - the cluster holds a **trust policy** that accepts tokens from this repository's `deploy.yaml`, on `main`, in the `production` environment, and lets them act as a deploy-only user.
129
129
 
130
- The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
130
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Install the CLI in that job and any `harper` command you add works the same way, without adding credentials.
131
131
 
132
132
  ### One-time setup
133
133
 
@@ -139,7 +139,7 @@ your-package-manager-run-here deploy:setup-ci
139
139
 
140
140
  It creates, on the cluster:
141
141
 
142
- - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
142
+ - a role that can run only `deploy_component`, `get_deployment` and `get_job` (to follow the rollout) and `registration_info` (the CLI's version check), and a user in it;
143
143
  - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
144
144
 
145
145
  With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_CLI_TARGET` repository variable; otherwise it prints the command to run. Running it again changes nothing. If something on the cluster already exists and differs, it stops and says what, without changing anything.
@@ -150,9 +150,9 @@ The deploy user can deploy any app on the cluster, so who can deploy comes down
150
150
 
151
151
  ### What a deploy does
152
152
 
153
- The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
153
+ The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, the run waits for every node, and each node first loads the release in a canary worker and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving. On an older cluster, the run passes as soon as the first node has the release.
154
154
 
155
- The run's summary names the deployment and its `certification`:
155
+ The deploy step's log names the deployment and its `certification`:
156
156
 
157
157
  - `certified`: the canary loaded the release.
158
158
  - `uncertified` or `unavailable`: the release went out without that check, for a reason the [deploy reference](https://docs.harperdb.io/reference/v5/operations-api/operations#certifying-a-release-in-a-canary-worker) lists.
@@ -176,6 +176,27 @@ your-package-manager-run-here deploy
176
176
 
177
177
  deploys this directory the same way, as the user you logged in with. It returns once the first node has the release; the response's `restartJobId` is the job that takes it to the others, which `harper get_job id=<restartJobId>` reports on.
178
178
 
179
+ ### Pull request previews
180
+
181
+ Turn these on and every pull request into `main` from a branch in this repository gets its own running copy of the app, at `https://<branch>.app.<your-cluster-host>/`, with its own branch of your databases. A comment on the pull request links to it. Each push updates it, and closing the pull request removes it; a preview that misses that expires after seven days.
182
+
183
+ The [preview workflow](./.github/workflows/preview.yaml) skips its jobs until you turn previews on. That takes Harper 5.4 or later on the cluster and on your machine. Run this once from the project, signed in as a super user:
184
+
185
+ ```sh
186
+ your-package-manager-run-here deploy:setup-previews
187
+ ```
188
+
189
+ It refuses a workflow with a job that runs for forks or checks out the pull request. Then it creates, on the cluster, a user that can only deploy and drop this app's previews, and trust policies for the workflow's `preview` and `preview-cleanup` environments. With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_PREVIEW_TARGET` repository variable, which is what turns the jobs on; otherwise it prints the command to run. To remove it all, previews included, run `harper preview teardown app=your-component-name-here`.
190
+
191
+ The workflow never checks out or builds a pull request. The cluster fetches the commit itself, then installs and builds it there. So anyone who can push a branch here, a bot included, can run code on your cluster, and Harper doesn't sandbox an app's code. A preview's writes stay in its own database branch, except in the `system` database (users and roles), which can't be branched.
192
+
193
+ - **Private repositories:** the cluster needs a credential to fetch each commit. Setup offers to seal one, and the workflow uses it whenever the repository is private.
194
+ - **Public repositories:** the workflow runs on `pull_request_target`, which [GitHub's default protection](https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target) blocks for affected public repositories from December 2, 2026. A blocked run fails with an error, even while previews are off. To allow it, go to **Settings → Actions → Policies**, create a policy with an active enforcement status that targets `.github/workflows/preview.yaml`, and add a **Restrict events** rule that allows `pull_request_target`. If you don't want previews, delete the workflow instead.
195
+ - **Forks:** pull requests from forks get no preview, and the cluster is never called for them.
196
+ - **Approvals:** to have a person approve each preview, add a required reviewer to the `preview` environment under **Settings → Environments**. Leave `preview-cleanup` without one, so closing a pull request never waits for an approval.
197
+
198
+ The [deploy action's documentation](https://github.com/HarperFast/deploy-action#pull-request-previews) covers the rest, such as using another domain and sweeping missed previews.
199
+
179
200
  ### When a run is refused
180
201
 
181
202
  If the deploy step fails with a 401, the cluster did not accept the run's token. `harper list_oidc_trust` shows each policy, and an `invalid_reason` when one can't match; the cluster's `oidc-trust` log says which check failed. Rerunning `your-package-manager-run-here deploy:setup-ci` reports a policy that no longer matches the workflow.
@@ -185,7 +206,7 @@ If the deploy step fails with a 401, the cluster did not accept the run's token.
185
206
  Projects created before this deployed on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and don't have this workflow or the `deploy:setup-ci` script. To move one over:
186
207
 
187
208
  1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
188
- 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
209
+ 2. Run the setup from the project, with the `app:` value the copied workflow passes to the deploy action: `harper deploy setup=true provider=github-actions project=<that value>`.
189
210
  3. Push the new workflow to `main`.
190
211
  4. Once nothing references it, delete the `HARPER_CLI_REFRESH_TOKEN` secret under **Settings → Secrets and variables → Actions**. The new workflow doesn't read it, so it is only a credential left lying around.
191
212
 
@@ -1,6 +1,6 @@
1
1
  # Tests every pull request, and deploys to your Harper cluster when a change merges to `main`. The
2
- # deploy job holds no Harper credential: its `harper` commands authenticate with GitHub's OIDC token
3
- # under a trust policy on the cluster. Set that up once with
2
+ # deploy job holds no Harper credential: HarperFast/deploy-action authenticates with GitHub's OIDC
3
+ # token under a trust policy on the cluster. Set that up once with
4
4
  # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README).
5
5
  name: Deploy to Harper
6
6
  on:
@@ -63,52 +63,14 @@ jobs:
63
63
  with:
64
64
  # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
65
65
  persist-credentials: false
66
- - name: Set up Node.js
67
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
68
- with:
69
- node-version-file: '.nvmrc'
70
- - name: Install Harper CLI
71
- # 5.3 is the first CLI that authenticates with the OIDC token.
72
- run: npm install --global harper@^5.3
73
- - name: Deploy
66
+ - name: Check the deploy target
67
+ # The action refuses an empty target too, but can't say which script sets it.
74
68
  run: |
75
- # With no target the CLI would fall back to a saved login or a local node, and succeed.
76
69
  [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
77
- harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
78
- - name: Wait for every node to take the release
79
- # The deploy returns once the node it reached has the release; the others take it in a job.
80
- run: |
81
- JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
82
- [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
83
- LAST="could not be read"
84
- for attempt in $(seq 60); do
85
- sleep 10
86
- harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
87
- case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
88
- COMPLETE) exit 0 ;;
89
- ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
90
- MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
91
- *) LAST="was still running" ;;
92
- esac
93
- done
94
- echo "::error::After 60 polls, job $JOB_ID $LAST"
95
- exit 1
96
- - name: Summarize
97
- if: ${{ !cancelled() }}
98
- env:
99
- JOB_STATUS: ${{ job.status }}
100
- run: |
101
- [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
102
- {
103
- if [ "$JOB_STATUS" = success ]; then
104
- echo "### Deployed your-component-name-here"
105
- elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
106
- echo "### Deploy of your-component-name-here did not complete on every node"
107
- else
108
- echo "### Deploy of your-component-name-here failed"
109
- fi
110
- jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
111
- echo ""
112
- echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
113
- echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
114
- } >> "$GITHUB_STEP_SUMMARY"
70
+ - name: Deploy
71
+ # From Harper 5.4 this waits for every node, and fails the run if a node's canary rejects the release.
72
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
73
+ with:
74
+ target: ${{ env.HARPER_CLI_TARGET }}
75
+ app: your-component-name-here
76
+ restart: rolling