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.
- package/README.md +10 -2
- package/lib/constants/helpMessage.js +4 -0
- package/lib/steps/installAndOptionallyStart.js +13 -1
- package/package.json +3 -2
- package/template-nextjs/README.md +11 -7
- package/template-nextjs/_github/workflows/deploy.yaml +11 -49
- package/template-nextjs-ts/README.md +11 -7
- package/template-nextjs-ts/_github/workflows/deploy.yaml +11 -49
- package/template-react/README.md +28 -7
- package/template-react/_github/workflows/deploy.yaml +11 -49
- package/template-react/_github/workflows/preview.yaml +54 -0
- package/template-react/package.json +2 -1
- package/template-react-ssr/README.md +28 -7
- package/template-react-ssr/_github/workflows/deploy.yaml +11 -49
- package/template-react-ssr/_github/workflows/preview.yaml +54 -0
- package/template-react-ssr/package.json +2 -1
- package/template-react-ts/README.md +28 -7
- package/template-react-ts/_github/workflows/deploy.yaml +11 -49
- package/template-react-ts/_github/workflows/preview.yaml +54 -0
- package/template-react-ts/package.json +2 -1
- package/template-react-ts-ssr/README.md +28 -7
- package/template-react-ts-ssr/_github/workflows/deploy.yaml +11 -49
- package/template-react-ts-ssr/_github/workflows/preview.yaml +54 -0
- package/template-react-ts-ssr/package.json +2 -1
- package/template-vanilla/README.md +28 -7
- package/template-vanilla/_github/workflows/deploy.yaml +11 -49
- package/template-vanilla/_github/workflows/preview.yaml +54 -0
- package/template-vanilla/package.json +2 -1
- package/template-vanilla-ts/README.md +28 -7
- package/template-vanilla-ts/_github/workflows/deploy.yaml +11 -49
- package/template-vanilla-ts/_github/workflows/preview.yaml +54 -0
- package/template-vanilla-ts/package.json +2 -1
- package/template-vue/README.md +28 -7
- package/template-vue/_github/workflows/deploy.yaml +11 -49
- package/template-vue/_github/workflows/preview.yaml +54 -0
- package/template-vue/package.json +2 -1
- package/template-vue-ssr/README.md +28 -7
- package/template-vue-ssr/_github/workflows/deploy.yaml +11 -49
- package/template-vue-ssr/_github/workflows/preview.yaml +54 -0
- package/template-vue-ssr/package.json +2 -1
- package/template-vue-ts/README.md +28 -7
- package/template-vue-ts/_github/workflows/deploy.yaml +11 -49
- package/template-vue-ts/_github/workflows/preview.yaml +54 -0
- package/template-vue-ts/package.json +2 -1
- package/template-vue-ts-ssr/README.md +28 -7
- package/template-vue-ts-ssr/_github/workflows/deploy.yaml +11 -49
- package/template-vue-ts-ssr/_github/workflows/preview.yaml +54 -0
- 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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
4
|
+
"version": "1.14.1",
|
|
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
|
|
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`
|
|
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'`.
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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:
|
|
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:
|
|
86
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
|
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`
|
|
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'`.
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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:
|
|
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:
|
|
86
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
package/template-react/README.md
CHANGED
|
@@ -113,13 +113,13 @@ harper login
|
|
|
113
113
|
|
|
114
114
|
### How the workflow authenticates
|
|
115
115
|
|
|
116
|
-
The workflow
|
|
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`
|
|
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'`.
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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:
|
|
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:
|
|
67
|
-
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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",
|