create-harper 1.12.12 → 1.13.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 (43) hide show
  1. package/README.md +18 -6
  2. package/lib/constants/helpMessage.js +3 -0
  3. package/lib/fs/copyFile.js +31 -15
  4. package/lib/pkg/toComponentName.js +20 -0
  5. package/lib/steps/installAndOptionallyStart.js +15 -0
  6. package/lib/steps/scaffoldProject.js +4 -0
  7. package/package.json +1 -1
  8. package/template-nextjs/README.md +65 -17
  9. package/template-nextjs/_github/workflows/deploy.yaml +99 -41
  10. package/template-nextjs/package.json +2 -1
  11. package/template-nextjs-ts/README.md +65 -17
  12. package/template-nextjs-ts/_github/workflows/deploy.yaml +99 -41
  13. package/template-nextjs-ts/package.json +2 -1
  14. package/template-react/README.md +57 -25
  15. package/template-react/_github/workflows/deploy.yaml +90 -39
  16. package/template-react/package.json +2 -2
  17. package/template-react-ssr/README.md +57 -25
  18. package/template-react-ssr/_github/workflows/deploy.yaml +90 -39
  19. package/template-react-ssr/package.json +2 -2
  20. package/template-react-ts/README.md +57 -25
  21. package/template-react-ts/_github/workflows/deploy.yaml +90 -39
  22. package/template-react-ts/package.json +2 -2
  23. package/template-react-ts-ssr/README.md +57 -25
  24. package/template-react-ts-ssr/_github/workflows/deploy.yaml +90 -39
  25. package/template-react-ts-ssr/package.json +2 -2
  26. package/template-vanilla/README.md +57 -25
  27. package/template-vanilla/_github/workflows/deploy.yaml +90 -39
  28. package/template-vanilla/package.json +5 -3
  29. package/template-vanilla-ts/README.md +57 -25
  30. package/template-vanilla-ts/_github/workflows/deploy.yaml +90 -39
  31. package/template-vanilla-ts/package.json +5 -3
  32. package/template-vue/README.md +57 -25
  33. package/template-vue/_github/workflows/deploy.yaml +90 -39
  34. package/template-vue/package.json +2 -2
  35. package/template-vue-ssr/README.md +57 -25
  36. package/template-vue-ssr/_github/workflows/deploy.yaml +90 -39
  37. package/template-vue-ssr/package.json +2 -2
  38. package/template-vue-ts/README.md +57 -25
  39. package/template-vue-ts/_github/workflows/deploy.yaml +90 -39
  40. package/template-vue-ts/package.json +2 -2
  41. package/template-vue-ts-ssr/README.md +57 -25
  42. package/template-vue-ts-ssr/_github/workflows/deploy.yaml +90 -39
  43. package/template-vue-ts-ssr/package.json +2 -2
@@ -1,48 +1,36 @@
1
- # Deploys this app to your Harper cluster by *payload* via `harper deploy_component .`
2
- # (`your-package-manager-run-here deploy`), which runs `next build` first and uploads the prebuilt
3
- # `.next` output.
4
- #
5
- # The other create-harper templates deploy by *reference* (`harper deploy by_ref=true`), where the
6
- # cluster clones your repo and builds on the node. Next.js can't use that yet: `.next` is gitignored
7
- # (so a git reference carries no build output) and building on the cluster currently fails —
8
- # Turbopack crashes inside a Harper worker thread (HarperFast/nextjs#57) and a webpack build
9
- # overruns the component-load timeout (HarperFast/nextjs#58). Once those land, this template can
10
- # switch to the by-reference workflow like the rest.
11
- #
12
- # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually.
13
- #
14
- # Required repository secrets (Settings → Secrets and variables → Actions):
15
- # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
16
- # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
17
- # token from it on each run, so no password is stored in CI
18
- #
19
- # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
20
- # never appears on screen or in your shell history:
21
- #
22
- # harper login --for-ci | gh secret set --env-file -
23
- name: Deploy to Harper Fabric
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
4
+ # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README). The deploy job
5
+ # runs `next build` and uploads it, because building on the cluster currently fails
6
+ # (HarperFast/nextjs#57, HarperFast/nextjs#58).
7
+ name: Deploy to Harper
24
8
  on:
25
- workflow_dispatch:
9
+ pull_request:
26
10
  push:
27
- tags:
28
- - 'v*'
11
+ branches: [main]
12
+ workflow_dispatch:
13
+
14
+ permissions:
15
+ contents: read
29
16
 
17
+ # One run per branch at a time, so an older commit can't deploy after a newer one; a newer run
18
+ # replaces one still waiting. On a pull request, a new push cancels the run in progress.
30
19
  concurrency:
31
- group: deploy
32
- cancel-in-progress: false
20
+ group: deploy-${{ github.ref }}
21
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
33
22
 
34
23
  jobs:
35
- deploy:
24
+ test:
36
25
  runs-on: ubuntu-latest
37
26
  steps:
38
27
  - name: Checkout code
39
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
28
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
40
29
  with:
41
- fetch-depth: 0
42
- fetch-tags: true
30
+ persist-credentials: false
43
31
  # your-package-manager-setup-step-here
44
32
  - name: Set up Node.js
45
- uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
33
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
46
34
  with:
47
35
  # your-package-manager-node-cache-here
48
36
  node-version-file: '.nvmrc'
@@ -50,13 +38,83 @@ jobs:
50
38
  run: your-package-manager-install-here
51
39
  - name: Run lint
52
40
  run: your-package-manager-run-here lint
41
+
42
+ deploy:
43
+ needs: test
44
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
45
+ runs-on: ubuntu-latest
46
+ environment: production
47
+ permissions:
48
+ contents: read
49
+ id-token: write
50
+ env:
51
+ HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
52
+ steps:
53
+ - name: Refuse to redeploy an older commit
54
+ # Re-running an old run keeps its commit, which would replace a newer release.
55
+ if: github.run_attempt > 1
56
+ env:
57
+ GH_TOKEN: ${{ github.token }}
58
+ run: |
59
+ HEAD=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_REF_NAME" --jq .sha)
60
+ [ "$HEAD" = "$GITHUB_SHA" ] || { echo "::error::$GITHUB_REF_NAME is now at $HEAD; re-running this deploy would replace it with $GITHUB_SHA"; exit 1; }
61
+ - name: Checkout code
62
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
63
+ with:
64
+ # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
65
+ persist-credentials: false
66
+ # your-package-manager-setup-step-here
67
+ - name: Set up Node.js
68
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
69
+ with:
70
+ # your-package-manager-node-cache-here
71
+ node-version-file: '.nvmrc'
72
+ - name: Install dependencies
73
+ run: your-package-manager-install-here
74
+ - name: Build
75
+ run: your-package-manager-run-here build
53
76
  - name: Install Harper CLI
54
- # Installed with npm regardless of this project's package manager: it is a global tool, and
55
- # npm always comes with the Node.js set up above. Pinned to the 5.2 line; ^5.2.0 blocks a
56
- # breaking 6.x bump.
57
- run: npm install -g harper@^5.2.0
58
- - name: Build & deploy
59
- run: your-package-manager-run-here deploy
77
+ # 5.3 is the first CLI that authenticates with the OIDC token.
78
+ run: npm install --global harper@^5.3
79
+ - name: Deploy
80
+ run: |
81
+ # With no target the CLI would fall back to a saved login or a local node, and succeed.
82
+ [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
83
+ harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
84
+ - name: Wait for every node to take the release
85
+ # The deploy returns once the node it reached has the release; the others take it in a job.
86
+ run: |
87
+ JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
88
+ [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
89
+ LAST="could not be read"
90
+ for attempt in $(seq 60); do
91
+ sleep 10
92
+ harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
93
+ case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
94
+ COMPLETE) exit 0 ;;
95
+ ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
96
+ MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
97
+ *) LAST="was still running" ;;
98
+ esac
99
+ done
100
+ echo "::error::After 60 polls, job $JOB_ID $LAST"
101
+ exit 1
102
+ - name: Summarize
103
+ if: ${{ !cancelled() }}
60
104
  env:
61
- HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
62
- HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
105
+ JOB_STATUS: ${{ job.status }}
106
+ run: |
107
+ [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
108
+ {
109
+ if [ "$JOB_STATUS" = success ]; then
110
+ echo "### Deployed your-component-name-here"
111
+ elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
112
+ echo "### Deploy of your-component-name-here did not complete on every node"
113
+ else
114
+ echo "### Deploy of your-component-name-here failed"
115
+ fi
116
+ jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
117
+ echo ""
118
+ echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
119
+ echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
120
+ } >> "$GITHUB_STEP_SUMMARY"
@@ -11,7 +11,8 @@
11
11
  "build": "next build",
12
12
  "lint": "eslint .",
13
13
  "format": "prettier --write .",
14
- "deploy": "next build && harper deploy_component . restart=true replicated=true"
14
+ "deploy": "next build && harper deploy project=your-component-name-here restart=rolling",
15
+ "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here"
15
16
  },
16
17
  "dependencies": {
17
18
  "@harperfast/nextjs": "^2.2.3",
@@ -103,61 +103,93 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
103
103
 
104
104
  ## Deployment
105
105
 
106
- Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
106
+ Your app deploys from GitHub: every pull request runs the tests, and merging to `main` deploys to your Harper cluster with the included [GitHub Actions workflow](./.github/workflows/deploy.yaml). No Harper password or token is stored in GitHub.
107
107
 
108
- First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
108
+ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it as a super user:
109
109
 
110
110
  ```sh
111
111
  harper login
112
112
  ```
113
113
 
114
- ### One-time setup (private repos)
114
+ ### How the workflow authenticates
115
115
 
116
- So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
116
+ The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
117
117
 
118
- ```sh
119
- your-package-manager-run-here deploy:setup
120
- ```
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;
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
- This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
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.
123
123
 
124
- > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
124
+ ### One-time setup
125
125
 
126
- ### Deploy
126
+ Push the project to a GitHub repository, then run this from the project on your machine. It needs Harper 5.4 or later (`npm install --global harper`):
127
127
 
128
128
  ```sh
129
- your-package-manager-run-here deploy
129
+ your-package-manager-run-here deploy:setup-ci
130
130
  ```
131
131
 
132
- This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
132
+ It creates, on the cluster:
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;
135
+ - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
136
+
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.
138
+
139
+ Then merge to `main`, or run the workflow from the **Actions** tab, to deploy.
140
+
141
+ The deploy user can deploy any app on the cluster, so who can deploy comes down to who can merge to `main`. Protect `main` under **Settings → Branches**, and if you want a person to approve each release, add a required reviewer to the `production` environment under **Settings → Environments**.
142
+
143
+ ### What a deploy does
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.
146
+
147
+ The run's summary names the deployment and its `certification`:
148
+
149
+ - `certified`: the canary loaded the release.
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.
133
151
 
134
- ### Deploy automatically from CI
152
+ ### Going back to an earlier release
135
153
 
136
- The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
154
+ Each node keeps the releases a deploy replaces. List them, then activate one by putting its `deployment_id` in place of `DEPLOYMENT_ID`; nothing is reinstalled:
137
155
 
138
156
  ```sh
139
- git tag v1.0.0
140
- git push --tags
157
+ harper list_deployments project=your-component-name-here
158
+ harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling
141
159
  ```
142
160
 
143
- Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
161
+ To have a person decide when a release goes live, deploy with `activate=false` instead: it installs the release without serving it, and prints a `deployment_id` you activate later with the second command above.
144
162
 
145
- - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
146
- - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
147
-
148
- Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
163
+ ### Deploying by hand
149
164
 
150
165
  ```sh
151
- harper login --for-ci | gh secret set --env-file -
166
+ your-package-manager-run-here deploy
152
167
  ```
153
168
 
154
- (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
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
+
171
+ ### When a run is refused
172
+
173
+ 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.
174
+
175
+ ### Moving from the earlier workflow
155
176
 
156
- The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
177
+ 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
+
179
+ 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>`.
181
+ 3. Push the new workflow to `main`.
182
+ 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.
157
183
 
158
184
  ### Private npm dependencies
159
185
 
160
- If your app depends on private npm packages, run `your-package-manager-run-here deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
186
+ The cluster installs your dependencies itself. If any come from a private npm registry, give the cluster a read-only token for it once. It is encrypted on your machine, and only the ciphertext is stored:
187
+
188
+ ```sh
189
+ harper deploy setup=true provider=npm project=your-component-name-here registry=https://npm.pkg.github.com scope=@your-org
190
+ ```
191
+
192
+ Leave out `registry=` and `scope=` for a private package on npmjs.com.
161
193
 
162
194
  ## Keep Going!
163
195
 
@@ -1,47 +1,34 @@
1
- # Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true`
2
- # (`your-package-manager-run-here deploy`).
3
- #
4
- # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster
5
- # fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a
6
- # moved tag), authenticating a private clone with the encrypted token you sealed once via
7
- # `your-package-manager-run-here deploy:setup`. The credential lives on the cluster, so this
8
- # workflow handles no token.
9
- #
10
- # Required repository secrets (Settings → Secrets and variables → Actions):
11
- # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
12
- # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
13
- # token from it on each run, so no password is stored in CI
14
- #
15
- # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
16
- # never appears on screen or in your shell history:
17
- #
18
- # harper login --for-ci | gh secret set --env-file -
19
- #
20
- # Public repo? Drop `credential=true` from the `deploy` script — no cluster-side auth needed.
21
- # See the "Deployment" section of the README for details.
22
- name: Deploy to Harper Fabric
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
4
+ # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README).
5
+ name: Deploy to Harper
23
6
  on:
24
- workflow_dispatch:
7
+ pull_request:
25
8
  push:
26
- tags:
27
- - 'v*'
9
+ branches: [main]
10
+ workflow_dispatch:
28
11
 
12
+ permissions:
13
+ contents: read
14
+
15
+ # One run per branch at a time, so an older commit can't deploy after a newer one; a newer run
16
+ # replaces one still waiting. On a pull request, a new push cancels the run in progress.
29
17
  concurrency:
30
- group: deploy
31
- cancel-in-progress: false
18
+ group: deploy-${{ github.ref }}
19
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
32
20
 
33
21
  jobs:
34
- deploy:
22
+ test:
35
23
  runs-on: ubuntu-latest
36
24
  steps:
37
25
  - name: Checkout code
38
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
26
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
39
27
  with:
40
- fetch-depth: 0
41
- fetch-tags: true
28
+ persist-credentials: false
42
29
  # your-package-manager-setup-step-here
43
30
  - name: Set up Node.js
44
- uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
31
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
45
32
  with:
46
33
  # your-package-manager-node-cache-here
47
34
  node-version-file: '.nvmrc'
@@ -51,13 +38,77 @@ jobs:
51
38
  run: your-package-manager-run-here test
52
39
  - name: Run lint
53
40
  run: your-package-manager-run-here lint
41
+
42
+ deploy:
43
+ needs: test
44
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
45
+ runs-on: ubuntu-latest
46
+ environment: production
47
+ permissions:
48
+ contents: read
49
+ id-token: write
50
+ env:
51
+ HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
52
+ steps:
53
+ - name: Refuse to redeploy an older commit
54
+ # Re-running an old run keeps its commit, which would replace a newer release.
55
+ if: github.run_attempt > 1
56
+ env:
57
+ GH_TOKEN: ${{ github.token }}
58
+ run: |
59
+ HEAD=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_REF_NAME" --jq .sha)
60
+ [ "$HEAD" = "$GITHUB_SHA" ] || { echo "::error::$GITHUB_REF_NAME is now at $HEAD; re-running this deploy would replace it with $GITHUB_SHA"; exit 1; }
61
+ - name: Checkout code
62
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
63
+ with:
64
+ # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
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'
54
70
  - name: Install Harper CLI
55
- # Installed with npm regardless of this project's package manager: it is a global tool, and
56
- # npm always comes with the Node.js set up above. Pinned to the 5.2 line (where
57
- # deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump.
58
- run: npm install -g harper@^5.2.0
71
+ # 5.3 is the first CLI that authenticates with the OIDC token.
72
+ run: npm install --global harper@^5.3
59
73
  - name: Deploy
60
- run: your-package-manager-run-here deploy
74
+ run: |
75
+ # With no target the CLI would fall back to a saved login or a local node, and succeed.
76
+ [ -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() }}
61
98
  env:
62
- HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
63
- HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
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"
@@ -13,8 +13,8 @@
13
13
  "test": "node --test test/*.test.js",
14
14
  "test:watch": "node --watch --test test/*.test.js",
15
15
  "build": "vite build",
16
- "deploy": "harper deploy by_ref=true credential=true restart=true replicated=true",
17
- "deploy:setup": "harper deploy setup=true"
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"
18
18
  },
19
19
  "dependencies": {
20
20
  "@harperfast/schema-codegen": "^2.0.0",
@@ -103,61 +103,93 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
103
103
 
104
104
  ## Deployment
105
105
 
106
- Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit.
106
+ Your app deploys from GitHub: every pull request runs the tests, and merging to `main` deploys to your Harper cluster with the included [GitHub Actions workflow](./.github/workflows/deploy.yaml). No Harper password or token is stored in GitHub.
107
107
 
108
- First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it:
108
+ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it as a super user:
109
109
 
110
110
  ```sh
111
111
  harper login
112
112
  ```
113
113
 
114
- ### One-time setup (private repos)
114
+ ### How the workflow authenticates
115
115
 
116
- So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
116
+ The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
117
117
 
118
- ```sh
119
- your-package-manager-run-here deploy:setup
120
- ```
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;
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
- This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid.
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.
123
123
 
124
- > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
124
+ ### One-time setup
125
125
 
126
- ### Deploy
126
+ Push the project to a GitHub repository, then run this from the project on your machine. It needs Harper 5.4 or later (`npm install --global harper`):
127
127
 
128
128
  ```sh
129
- your-package-manager-run-here deploy
129
+ your-package-manager-run-here deploy:setup-ci
130
130
  ```
131
131
 
132
- This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again.
132
+ It creates, on the cluster:
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;
135
+ - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
136
+
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.
138
+
139
+ Then merge to `main`, or run the workflow from the **Actions** tab, to deploy.
140
+
141
+ The deploy user can deploy any app on the cluster, so who can deploy comes down to who can merge to `main`. Protect `main` under **Settings → Branches**, and if you want a person to approve each release, add a required reviewer to the `production` environment under **Settings → Environments**.
142
+
143
+ ### What a deploy does
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.
146
+
147
+ The run's summary names the deployment and its `certification`:
148
+
149
+ - `certified`: the canary loaded the release.
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.
133
151
 
134
- ### Deploy automatically from CI
152
+ ### Going back to an earlier release
135
153
 
136
- The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
154
+ Each node keeps the releases a deploy replaces. List them, then activate one by putting its `deployment_id` in place of `DEPLOYMENT_ID`; nothing is reinstalled:
137
155
 
138
156
  ```sh
139
- git tag v1.0.0
140
- git push --tags
157
+ harper list_deployments project=your-component-name-here
158
+ harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling
141
159
  ```
142
160
 
143
- Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
161
+ To have a person decide when a release goes live, deploy with `activate=false` instead: it installs the release without serving it, and prints a `deployment_id` you activate later with the second command above.
144
162
 
145
- - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
146
- - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
147
-
148
- Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
163
+ ### Deploying by hand
149
164
 
150
165
  ```sh
151
- harper login --for-ci | gh secret set --env-file -
166
+ your-package-manager-run-here deploy
152
167
  ```
153
168
 
154
- (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
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
+
171
+ ### When a run is refused
172
+
173
+ 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.
174
+
175
+ ### Moving from the earlier workflow
155
176
 
156
- The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
177
+ 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
+
179
+ 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>`.
181
+ 3. Push the new workflow to `main`.
182
+ 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.
157
183
 
158
184
  ### Private npm dependencies
159
185
 
160
- If your app depends on private npm packages, run `your-package-manager-run-here deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential.
186
+ The cluster installs your dependencies itself. If any come from a private npm registry, give the cluster a read-only token for it once. It is encrypted on your machine, and only the ciphertext is stored:
187
+
188
+ ```sh
189
+ harper deploy setup=true provider=npm project=your-component-name-here registry=https://npm.pkg.github.com scope=@your-org
190
+ ```
191
+
192
+ Leave out `registry=` and `scope=` for a private package on npmjs.com.
161
193
 
162
194
  ## Keep Going!
163
195