create-harper 1.13.7 → 1.14.0

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
package/README.md CHANGED
@@ -76,7 +76,7 @@ You can use `.` for the project name to scaffold in the current directory.
76
76
 
77
77
  Every project comes with a GitHub Actions workflow that tests pull requests and deploys to your [Harper Fabric](https://fabric.harper.fast/) cluster when a change merges to `main`. It stores no Harper credential: the deploy job authenticates with GitHub's OIDC identity token, which the cluster accepts under a trust policy.
78
78
 
79
- After you push the new project to GitHub, set that up once from the project, signed in to the cluster as a super user with `harper login` (Harper 5.4 or later):
79
+ After you push the new project to GitHub, set that up once from the project, signed in to the cluster as a super user with `harper login`, using the Harper 5.4 CLI or later:
80
80
 
81
81
  ```bash
82
82
  npm run deploy:setup-ci
@@ -84,7 +84,15 @@ npm run deploy:setup-ci
84
84
 
85
85
  It creates a deploy-only user and the trust policy on the cluster, and sets the workflow's `HARPER_CLI_TARGET` repository variable. Each project's README covers the rest: going back to an earlier release, staging a release, and what to do when a run is refused.
86
86
 
87
- Projects created before this deploy on version tags with a stored `HARPER_CLI_REFRESH_TOKEN`. To move one over, scaffold a new project with the same name, template and package manager, copy its `.github/workflows/deploy.yaml` over yours, run `harper deploy setup=true provider=github-actions project=<the workflow's project= value>`, push, and then delete the old secret.
87
+ Most templates can also give each pull request its own preview on the cluster, which takes Harper 5.4 or later there and on your machine. The workflow does nothing until you turn it on, once, with:
88
+
89
+ ```bash
90
+ npm run deploy:setup-previews
91
+ ```
92
+
93
+ It runs on `pull_request_target`, which GitHub's default protection blocks for affected public repositories from December 2, 2026, so a public repository must allow that event; the project's README says how. The `nextjs` and `nextjs-ts` templates don't have previews yet, because a preview deploys a commit, which has no `.next` build in it.
94
+
95
+ Projects created before this deploy on version tags with a stored `HARPER_CLI_REFRESH_TOKEN`. To move one over, scaffold a new project with the same name, template and package manager, copy its `.github/workflows/deploy.yaml` over yours, run `harper deploy setup=true provider=github-actions project=<the workflow's app: value>`, push, and then delete the old secret.
88
96
 
89
97
  ## Auto-updates
90
98
 
@@ -41,5 +41,9 @@ If you are going to deploy your application to https://fabric.harper.fast/, you
41
41
  Projects deploy from GitHub Actions when a change merges to main. After pushing the project to GitHub, run
42
42
  its "deploy:setup-ci" script once to let the workflow deploy to your cluster (see the project's README).
43
43
 
44
+ Pull requests can each get a preview on your cluster, which needs Harper 5.4 or later. Run the project's
45
+ "deploy:setup-previews" script once to turn that on (the nextjs templates don't have previews yet). A public
46
+ repository must also allow pull_request_target, which GitHub blocks by default from December 2, 2026.
47
+
44
48
  Available templates:
45
49
  ${availableTemplates}`;
@@ -22,7 +22,18 @@ export function installAndOptionallyStart(root, pkgManager, immediate, skipInsta
22
22
  }
23
23
 
24
24
  // The scaffolder can't do this setup itself: the GitHub repository rarely exists yet.
25
- if (fs.existsSync(path.join(root, '.github', 'workflows', 'deploy.yaml'))) {
25
+ const workflows = path.join(root, '.github', 'workflows');
26
+ if (fs.existsSync(path.join(workflows, 'deploy.yaml'))) {
27
+ const previews = fs.existsSync(path.join(workflows, 'preview.yaml'))
28
+ ? [
29
+ '',
30
+ `For a preview of each pull request (Harper 5.4): ${
31
+ getRunCommand(pkgManager, 'deploy:setup-previews').join(' ')
32
+ }`,
33
+ 'A public repository must also allow pull_request_target; GitHub blocks it by default from',
34
+ 'December 2, 2026. See "Pull request previews" in README.md.',
35
+ ]
36
+ : [];
26
37
  prompts.note(
27
38
  [
28
39
  '1. Push this project to a GitHub repository.',
@@ -30,6 +41,7 @@ export function installAndOptionallyStart(root, pkgManager, immediate, skipInsta
30
41
  `3. ${getRunCommand(pkgManager, 'deploy:setup-ci').join(' ')}`,
31
42
  '',
32
43
  'Then merging to main deploys. See "Deployment" in README.md.',
44
+ ...previews,
33
45
  ].join('\n'),
34
46
  'Deploy from GitHub',
35
47
  );
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "create-harper",
3
3
  "description": "Scaffold a new Harper project in JavaScript or TypeScript.",
4
- "version": "1.13.7",
4
+ "version": "1.14.0",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "exports": {
@@ -83,6 +83,7 @@
83
83
  "dprint": "^0.64.0",
84
84
  "oxlint": "^1.38.0",
85
85
  "semantic-release": "^25.0.2",
86
- "vitest": "^5.0.0"
86
+ "vitest": "^5.0.0",
87
+ "yaml": "^2.9.1"
87
88
  }
88
89
  }
@@ -66,13 +66,13 @@ harper login
66
66
 
67
67
  ### How the workflow authenticates
68
68
 
69
- The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
69
+ 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:
70
70
 
71
71
  - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
72
- - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
72
+ - the `HARPER_CLI_TARGET` repository variable holds your cluster's URL, so the CLI asks for a token addressed to that cluster;
73
73
  - 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.
74
74
 
75
- 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.
75
+ 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.
76
76
 
77
77
  ### One-time setup
78
78
 
@@ -84,7 +84,7 @@ your-package-manager-run-here deploy:setup-ci
84
84
 
85
85
  It creates, on the cluster:
86
86
 
87
- - 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;
87
+ - 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;
88
88
  - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
89
89
 
90
90
  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.
@@ -95,9 +95,9 @@ The deploy user can deploy any app on the cluster, so who can deploy comes down
95
95
 
96
96
  ### What a deploy does
97
97
 
98
- The workflow's test job runs `next build`, and the deploy job uploads the project with that `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). The build stays out of the deploy job, so your dependencies' install and build scripts never run where the OIDC token can be requested. It deploys 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.
98
+ The workflow's test job runs `next build`, and the deploy job uploads the project with that `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). The build stays out of the deploy job, so your dependencies' install and build scripts never run where the OIDC token can be requested. It deploys 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.
99
99
 
100
- The run's summary names the deployment and its `certification`:
100
+ The deploy step's log names the deployment and its `certification`:
101
101
 
102
102
  - `certified`: the canary loaded the release.
103
103
  - `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.
@@ -121,6 +121,10 @@ your-package-manager-run-here deploy
121
121
 
122
122
  builds and 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.
123
123
 
124
+ ### Pull request previews
125
+
126
+ This template doesn't have pull request previews yet. A preview has the cluster fetch the pull request's commit, which has no `.next` build in it, and building on the cluster currently fails (see the note in [`config.yaml`](./config.yaml)). Don't run `harper preview setup` on this project: a preview deployed that way reports success and then serves nothing.
127
+
124
128
  ### When a run is refused
125
129
 
126
130
  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.
@@ -130,7 +134,7 @@ If the deploy step fails with a 401, the cluster did not accept the run's token.
130
134
  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:
131
135
 
132
136
  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.
133
- 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>`.
137
+ 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>`.
134
138
  3. Push the new workflow to `main`.
135
139
  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.
136
140
 
@@ -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). The test job
5
5
  # runs `next build` and hands it to the deploy job, which uploads it, because building on the cluster
6
6
  # currently fails (HarperFast/nextjs#57, HarperFast/nextjs#58).
@@ -82,52 +82,14 @@ jobs:
82
82
  with:
83
83
  name: next-build
84
84
  path: .next
85
- - name: Set up Node.js
86
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
87
- with:
88
- node-version-file: '.nvmrc'
89
- - name: Install Harper CLI
90
- # 5.3 is the first CLI that authenticates with the OIDC token.
91
- run: npm install --global harper@^5.3
92
- - name: Deploy
85
+ - name: Check the deploy target
86
+ # The action refuses an empty target too, but can't say which script sets it.
93
87
  run: |
94
- # With no target the CLI would fall back to a saved login or a local node, and succeed.
95
88
  [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
96
- harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
97
- - name: Wait for every node to take the release
98
- # The deploy returns once the node it reached has the release; the others take it in a job.
99
- run: |
100
- JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
101
- [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
102
- LAST="could not be read"
103
- for attempt in $(seq 60); do
104
- sleep 10
105
- harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
106
- case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
107
- COMPLETE) exit 0 ;;
108
- ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
109
- MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
110
- *) LAST="was still running" ;;
111
- esac
112
- done
113
- echo "::error::After 60 polls, job $JOB_ID $LAST"
114
- exit 1
115
- - name: Summarize
116
- if: ${{ !cancelled() }}
117
- env:
118
- JOB_STATUS: ${{ job.status }}
119
- run: |
120
- [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
121
- {
122
- if [ "$JOB_STATUS" = success ]; then
123
- echo "### Deployed your-component-name-here"
124
- elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
125
- echo "### Deploy of your-component-name-here did not complete on every node"
126
- else
127
- echo "### Deploy of your-component-name-here failed"
128
- fi
129
- jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
130
- echo ""
131
- echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
132
- echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
133
- } >> "$GITHUB_STEP_SUMMARY"
89
+ - name: Deploy
90
+ # From Harper 5.4 this waits for every node, and fails the run if a node's canary rejects the release.
91
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
92
+ with:
93
+ target: ${{ env.HARPER_CLI_TARGET }}
94
+ app: your-component-name-here
95
+ restart: rolling
@@ -66,13 +66,13 @@ harper login
66
66
 
67
67
  ### How the workflow authenticates
68
68
 
69
- The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
69
+ 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:
70
70
 
71
71
  - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
72
- - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
72
+ - the `HARPER_CLI_TARGET` repository variable holds your cluster's URL, so the CLI asks for a token addressed to that cluster;
73
73
  - 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.
74
74
 
75
- 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.
75
+ 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.
76
76
 
77
77
  ### One-time setup
78
78
 
@@ -84,7 +84,7 @@ your-package-manager-run-here deploy:setup-ci
84
84
 
85
85
  It creates, on the cluster:
86
86
 
87
- - 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;
87
+ - 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;
88
88
  - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
89
89
 
90
90
  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.
@@ -95,9 +95,9 @@ The deploy user can deploy any app on the cluster, so who can deploy comes down
95
95
 
96
96
  ### What a deploy does
97
97
 
98
- The workflow's test job runs `next build`, and the deploy job uploads the project with that `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). The build stays out of the deploy job, so your dependencies' install and build scripts never run where the OIDC token can be requested. It deploys 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.
98
+ The workflow's test job runs `next build`, and the deploy job uploads the project with that `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). The build stays out of the deploy job, so your dependencies' install and build scripts never run where the OIDC token can be requested. It deploys 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.
99
99
 
100
- The run's summary names the deployment and its `certification`:
100
+ The deploy step's log names the deployment and its `certification`:
101
101
 
102
102
  - `certified`: the canary loaded the release.
103
103
  - `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.
@@ -121,6 +121,10 @@ your-package-manager-run-here deploy
121
121
 
122
122
  builds and 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.
123
123
 
124
+ ### Pull request previews
125
+
126
+ This template doesn't have pull request previews yet. A preview has the cluster fetch the pull request's commit, which has no `.next` build in it, and building on the cluster currently fails (see the note in [`config.yaml`](./config.yaml)). Don't run `harper preview setup` on this project: a preview deployed that way reports success and then serves nothing.
127
+
124
128
  ### When a run is refused
125
129
 
126
130
  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.
@@ -130,7 +134,7 @@ If the deploy step fails with a 401, the cluster did not accept the run's token.
130
134
  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:
131
135
 
132
136
  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.
133
- 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>`.
137
+ 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>`.
134
138
  3. Push the new workflow to `main`.
135
139
  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.
136
140
 
@@ -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). The test job
5
5
  # runs `next build` and hands it to the deploy job, which uploads it, because building on the cluster
6
6
  # currently fails (HarperFast/nextjs#57, HarperFast/nextjs#58).
@@ -82,52 +82,14 @@ jobs:
82
82
  with:
83
83
  name: next-build
84
84
  path: .next
85
- - name: Set up Node.js
86
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
87
- with:
88
- node-version-file: '.nvmrc'
89
- - name: Install Harper CLI
90
- # 5.3 is the first CLI that authenticates with the OIDC token.
91
- run: npm install --global harper@^5.3
92
- - name: Deploy
85
+ - name: Check the deploy target
86
+ # The action refuses an empty target too, but can't say which script sets it.
93
87
  run: |
94
- # With no target the CLI would fall back to a saved login or a local node, and succeed.
95
88
  [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
96
- harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
97
- - name: Wait for every node to take the release
98
- # The deploy returns once the node it reached has the release; the others take it in a job.
99
- run: |
100
- JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
101
- [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
102
- LAST="could not be read"
103
- for attempt in $(seq 60); do
104
- sleep 10
105
- harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
106
- case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
107
- COMPLETE) exit 0 ;;
108
- ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
109
- MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
110
- *) LAST="was still running" ;;
111
- esac
112
- done
113
- echo "::error::After 60 polls, job $JOB_ID $LAST"
114
- exit 1
115
- - name: Summarize
116
- if: ${{ !cancelled() }}
117
- env:
118
- JOB_STATUS: ${{ job.status }}
119
- run: |
120
- [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
121
- {
122
- if [ "$JOB_STATUS" = success ]; then
123
- echo "### Deployed your-component-name-here"
124
- elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
125
- echo "### Deploy of your-component-name-here did not complete on every node"
126
- else
127
- echo "### Deploy of your-component-name-here failed"
128
- fi
129
- jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
130
- echo ""
131
- echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
132
- echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
133
- } >> "$GITHUB_STEP_SUMMARY"
89
+ - name: Deploy
90
+ # From Harper 5.4 this waits for every node, and fails the run if a node's canary rejects the release.
91
+ uses: HarperFast/deploy-action@45fa59b6157eabb72b7a74922309238671f2a37d # v1.0.0
92
+ with:
93
+ target: ${{ env.HARPER_CLI_TARGET }}
94
+ app: your-component-name-here
95
+ restart: rolling
@@ -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",