create-harper 1.12.12 → 1.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (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 +2 -2
  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,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.ts",
14
14
  "test:watch": "node --watch --test test/*.test.ts",
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
 
@@ -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"
@@ -12,12 +12,14 @@
12
12
  "format": "prettier --write .",
13
13
  "test": "node --test test/*.test.js",
14
14
  "test:watch": "node --watch --test test/*.test.js",
15
- "deploy": "harper deploy by_ref=true credential=true restart=true replicated=true",
16
- "deploy:setup": "harper deploy setup=true"
15
+ "deploy": "harper deploy project=your-component-name-here restart=rolling",
16
+ "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here"
17
+ },
18
+ "dependencies": {
19
+ "@harperfast/schema-codegen": "^2.0.0"
17
20
  },
18
21
  "devDependencies": {
19
22
  "@eslint/js": "^10.0.1",
20
- "@harperfast/schema-codegen": "^2.0.0",
21
23
  "eslint": "^10.0.2",
22
24
  "globals": "^17.4.0",
23
25
  "prettier": "^3.8.1"
@@ -111,61 +111,93 @@ Take a look at the [default configuration](./config.yaml), which specifies how f
111
111
 
112
112
  ## Deployment
113
113
 
114
- 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.
114
+ 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.
115
115
 
116
- 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:
116
+ 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:
117
117
 
118
118
  ```sh
119
119
  harper login
120
120
  ```
121
121
 
122
- ### One-time setup (private repos)
122
+ ### How the workflow authenticates
123
123
 
124
- So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted:
124
+ The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
125
125
 
126
- ```sh
127
- your-package-manager-run-here deploy:setup
128
- ```
126
+ - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
127
+ - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
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
- 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.
130
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
131
131
 
132
- > Public repo? Skip this step and drop `credential=true` from the `deploy` script — no credential is needed.
132
+ ### One-time setup
133
133
 
134
- ### Deploy
134
+ 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`):
135
135
 
136
136
  ```sh
137
- your-package-manager-run-here deploy
137
+ your-package-manager-run-here deploy:setup-ci
138
138
  ```
139
139
 
140
- 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.
140
+ It creates, on the cluster:
141
+
142
+ - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
143
+ - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
144
+
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.
146
+
147
+ Then merge to `main`, or run the workflow from the **Actions** tab, to deploy.
148
+
149
+ 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**.
150
+
151
+ ### What a deploy does
152
+
153
+ The workflow uploads the checked-out project and deploys it with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
154
+
155
+ The run's summary names the deployment and its `certification`:
156
+
157
+ - `certified`: the canary loaded the release.
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.
141
159
 
142
- ### Deploy automatically from CI
160
+ ### Going back to an earlier release
143
161
 
144
- The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag:
162
+ 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:
145
163
 
146
164
  ```sh
147
- git tag v1.0.0
148
- git push --tags
165
+ harper list_deployments project=your-component-name-here
166
+ harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling
149
167
  ```
150
168
 
151
- Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
169
+ 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.
152
170
 
153
- - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
154
- - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
155
-
156
- 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:
171
+ ### Deploying by hand
157
172
 
158
173
  ```sh
159
- harper login --for-ci | gh secret set --env-file -
174
+ your-package-manager-run-here deploy
160
175
  ```
161
176
 
162
- (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
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
+
179
+ ### When a run is refused
180
+
181
+ 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.
182
+
183
+ ### Moving from the earlier workflow
163
184
 
164
- The clone credential already lives in the cluster from `your-package-manager-run-here deploy:setup`, so CI never handles a token itself.
185
+ 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
+
187
+ 1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
188
+ 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
189
+ 3. Push the new workflow to `main`.
190
+ 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.
165
191
 
166
192
  ### Private npm dependencies
167
193
 
168
- 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.
194
+ 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:
195
+
196
+ ```sh
197
+ harper deploy setup=true provider=npm project=your-component-name-here registry=https://npm.pkg.github.com scope=@your-org
198
+ ```
199
+
200
+ Leave out `registry=` and `scope=` for a private package on npmjs.com.
169
201
 
170
202
  ## Keep Going!
171
203