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.
- package/README.md +18 -6
- package/lib/constants/helpMessage.js +3 -0
- package/lib/fs/copyFile.js +31 -15
- package/lib/pkg/toComponentName.js +20 -0
- package/lib/steps/installAndOptionallyStart.js +15 -0
- package/lib/steps/scaffoldProject.js +4 -0
- package/package.json +1 -1
- package/template-nextjs/README.md +65 -17
- package/template-nextjs/_github/workflows/deploy.yaml +99 -41
- package/template-nextjs/package.json +2 -1
- package/template-nextjs-ts/README.md +65 -17
- package/template-nextjs-ts/_github/workflows/deploy.yaml +99 -41
- package/template-nextjs-ts/package.json +2 -1
- package/template-react/README.md +57 -25
- package/template-react/_github/workflows/deploy.yaml +90 -39
- package/template-react/package.json +2 -2
- package/template-react-ssr/README.md +57 -25
- package/template-react-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-react-ssr/package.json +2 -2
- package/template-react-ts/README.md +57 -25
- package/template-react-ts/_github/workflows/deploy.yaml +90 -39
- package/template-react-ts/package.json +2 -2
- package/template-react-ts-ssr/README.md +57 -25
- package/template-react-ts-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-react-ts-ssr/package.json +2 -2
- package/template-vanilla/README.md +57 -25
- package/template-vanilla/_github/workflows/deploy.yaml +90 -39
- package/template-vanilla/package.json +5 -3
- package/template-vanilla-ts/README.md +57 -25
- package/template-vanilla-ts/_github/workflows/deploy.yaml +90 -39
- package/template-vanilla-ts/package.json +5 -3
- package/template-vue/README.md +57 -25
- package/template-vue/_github/workflows/deploy.yaml +90 -39
- package/template-vue/package.json +2 -2
- package/template-vue-ssr/README.md +57 -25
- package/template-vue-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-vue-ssr/package.json +2 -2
- package/template-vue-ts/README.md +57 -25
- package/template-vue-ts/_github/workflows/deploy.yaml +90 -39
- package/template-vue-ts/package.json +2 -2
- package/template-vue-ts-ssr/README.md +57 -25
- package/template-vue-ts-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-vue-ts-ssr/package.json +2 -2
|
@@ -1,47 +1,34 @@
|
|
|
1
|
-
#
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
pull_request:
|
|
25
8
|
push:
|
|
26
|
-
|
|
27
|
-
|
|
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:
|
|
18
|
+
group: deploy-${{ github.ref }}
|
|
19
|
+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
|
32
20
|
|
|
33
21
|
jobs:
|
|
34
|
-
|
|
22
|
+
test:
|
|
35
23
|
runs-on: ubuntu-latest
|
|
36
24
|
steps:
|
|
37
25
|
- name: Checkout code
|
|
38
|
-
uses: actions/checkout@
|
|
26
|
+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
39
27
|
with:
|
|
40
|
-
|
|
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@
|
|
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
|
-
#
|
|
56
|
-
|
|
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:
|
|
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
|
-
|
|
63
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
###
|
|
114
|
+
### How the workflow authenticates
|
|
115
115
|
|
|
116
|
-
|
|
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
|
-
|
|
119
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
+
### One-time setup
|
|
125
125
|
|
|
126
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
152
|
+
### Going back to an earlier release
|
|
135
153
|
|
|
136
|
-
|
|
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
|
-
|
|
140
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
166
|
+
your-package-manager-run-here deploy
|
|
152
167
|
```
|
|
153
168
|
|
|
154
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
pull_request:
|
|
25
8
|
push:
|
|
26
|
-
|
|
27
|
-
|
|
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:
|
|
18
|
+
group: deploy-${{ github.ref }}
|
|
19
|
+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
|
32
20
|
|
|
33
21
|
jobs:
|
|
34
|
-
|
|
22
|
+
test:
|
|
35
23
|
runs-on: ubuntu-latest
|
|
36
24
|
steps:
|
|
37
25
|
- name: Checkout code
|
|
38
|
-
uses: actions/checkout@
|
|
26
|
+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
39
27
|
with:
|
|
40
|
-
|
|
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@
|
|
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
|
-
#
|
|
56
|
-
|
|
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:
|
|
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
|
-
|
|
63
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
###
|
|
122
|
+
### How the workflow authenticates
|
|
123
123
|
|
|
124
|
-
|
|
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
|
-
|
|
127
|
-
|
|
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
|
-
|
|
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
|
-
|
|
132
|
+
### One-time setup
|
|
133
133
|
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
160
|
+
### Going back to an earlier release
|
|
143
161
|
|
|
144
|
-
|
|
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
|
-
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
174
|
+
your-package-manager-run-here deploy
|
|
160
175
|
```
|
|
161
176
|
|
|
162
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|