create-harper 1.13.6 → 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.
- 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
|
@@ -121,13 +121,13 @@ harper login
|
|
|
121
121
|
|
|
122
122
|
### How the workflow authenticates
|
|
123
123
|
|
|
124
|
-
The workflow
|
|
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`
|
|
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'`.
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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:
|
|
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.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",
|