Skip to content

Commit a2a7fbb

Browse files
ci: check every push and PR; deploy main to production, any ref to staging
- checks.yml (reusable): npm ci, lint, format check, build. - ci.yml: runs the checks on every push and pull request; a push to main that passes deploys to the production environment. - deploy-staging.yml: manual (workflow_dispatch) deploy of a branch, tag, commit, or pull request number to the staging environment, after the same checks. - deploy.yml (reusable): writes .env from the environment's secrets and variables (the app loads its OAuth settings from .env, and harper deploy ships the working directory), runs npm run deploy, then scripts/check-site.sh. - scripts/check-site.sh: waits for three consecutive healthy page loads; if the site isn't healthy in time (typically the missing .harper-vite-ssr render bundle after a deploy), restarts the HTTP workers on every node once and checks again, failing the job if that doesn't fix it. The README's deploy section now describes this pipeline and the settings each environment needs, replacing the description of a CI setup that didn't exist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b576fcc commit a2a7fbb

6 files changed

Lines changed: 260 additions & 16 deletions

File tree

‎.github/workflows/checks.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Lint, format check, and build at a given ref. Called by CI on every push and
2+
# pull request, and by the staging deploy before it ships anything.
3+
name: Checks
4+
5+
on:
6+
workflow_call:
7+
inputs:
8+
ref:
9+
description: Git ref to check out (defaults to the triggering commit)
10+
type: string
11+
default: ''
12+
13+
permissions:
14+
contents: read
15+
16+
jobs:
17+
checks:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v5
21+
with:
22+
ref: ${{ inputs.ref }}
23+
- uses: actions/setup-node@v5
24+
with:
25+
node-version: 24
26+
cache: npm
27+
- run: npm ci
28+
- run: npm run lint
29+
- run: npm run format:check
30+
- run: npm run build

‎.github/workflows/ci.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Every push and pull request runs the checks; a push to main that passes
2+
# deploys to production.
3+
name: CI
4+
5+
on:
6+
push:
7+
branches: [main]
8+
pull_request:
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
checks:
15+
uses: ./.github/workflows/checks.yml
16+
17+
deploy-production:
18+
needs: checks
19+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
20+
uses: ./.github/workflows/deploy.yml
21+
with:
22+
environment: production
23+
ref: ${{ github.sha }}
24+
secrets: inherit
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Manually deploy any branch, tag, commit, or pull request to staging. Only
2+
# people with write access can run it. A pull request from a fork runs on the
3+
# staging instance with staging's secrets, so review it before deploying.
4+
name: Deploy to staging
5+
6+
on:
7+
workflow_dispatch:
8+
inputs:
9+
ref:
10+
description: Branch, tag, or commit SHA to deploy
11+
type: string
12+
default: main
13+
pr:
14+
description: Pull request number to deploy instead (overrides ref)
15+
type: string
16+
default: ''
17+
18+
permissions:
19+
contents: read
20+
21+
jobs:
22+
checks:
23+
uses: ./.github/workflows/checks.yml
24+
with:
25+
ref: ${{ inputs.pr && format('refs/pull/{0}/head', inputs.pr) || inputs.ref }}
26+
27+
deploy-staging:
28+
needs: checks
29+
uses: ./.github/workflows/deploy.yml
30+
with:
31+
environment: staging
32+
ref: ${{ inputs.pr && format('refs/pull/{0}/head', inputs.pr) || inputs.ref }}
33+
secrets: inherit

‎.github/workflows/deploy.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Deploys a ref to one Harper Fabric environment (production or staging).
2+
#
3+
# Each GitHub environment holds:
4+
# secrets HARPER_CLI_USERNAME, HARPER_CLI_PASSWORD,
5+
# OAUTH_GITHUB_CLIENT_ID, OAUTH_GITHUB_CLIENT_SECRET
6+
# variables SITE_URL, HARPER_CLI_TARGET (the cluster's operations URL),
7+
# OAUTH_REDIRECT_URI, ADMIN_GITHUB_LOGINS (optional)
8+
# The last three may be secrets instead, so a whole .env can be loaded with
9+
# `gh secret set --env <name> -f .env`.
10+
#
11+
# The app reads its OAuth settings from .env (config.yaml loadEnv), and
12+
# `harper deploy` ships the working directory, so the job writes .env from
13+
# the environment's settings right before deploying.
14+
name: Deploy
15+
16+
on:
17+
workflow_call:
18+
inputs:
19+
environment:
20+
description: GitHub environment to deploy to
21+
type: string
22+
required: true
23+
ref:
24+
description: Git ref to deploy
25+
type: string
26+
required: true
27+
28+
permissions:
29+
contents: read
30+
31+
jobs:
32+
deploy:
33+
runs-on: ubuntu-latest
34+
environment:
35+
name: ${{ inputs.environment }}
36+
url: ${{ vars.SITE_URL }}
37+
# One deploy per environment at a time; a newer one waits rather than
38+
# cancelling a deploy that is already running.
39+
concurrency:
40+
group: deploy-${{ inputs.environment }}
41+
cancel-in-progress: false
42+
env:
43+
HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET || secrets.HARPER_CLI_TARGET }}
44+
HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }}
45+
HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }}
46+
steps:
47+
- uses: actions/checkout@v5
48+
with:
49+
ref: ${{ inputs.ref }}
50+
- uses: actions/setup-node@v5
51+
with:
52+
node-version: 24
53+
cache: npm
54+
- run: npm ci
55+
56+
- name: Write the runtime .env
57+
env:
58+
OAUTH_GITHUB_CLIENT_ID: ${{ secrets.OAUTH_GITHUB_CLIENT_ID }}
59+
OAUTH_GITHUB_CLIENT_SECRET: ${{ secrets.OAUTH_GITHUB_CLIENT_SECRET }}
60+
OAUTH_REDIRECT_URI: ${{ vars.OAUTH_REDIRECT_URI || secrets.OAUTH_REDIRECT_URI }}
61+
ADMIN_GITHUB_LOGINS: ${{ vars.ADMIN_GITHUB_LOGINS || secrets.ADMIN_GITHUB_LOGINS }}
62+
run: |
63+
for key in HARPER_CLI_TARGET HARPER_CLI_USERNAME HARPER_CLI_PASSWORD \
64+
OAUTH_GITHUB_CLIENT_ID OAUTH_GITHUB_CLIENT_SECRET OAUTH_REDIRECT_URI; do
65+
if [ -z "${!key}" ]; then
66+
echo "::error::$key is not set for the ${{ inputs.environment }} environment"
67+
exit 1
68+
fi
69+
done
70+
: > .env
71+
for key in OAUTH_GITHUB_CLIENT_ID OAUTH_GITHUB_CLIENT_SECRET OAUTH_REDIRECT_URI ADMIN_GITHUB_LOGINS; do
72+
printf '%s=%s\n' "$key" "${!key}" >> .env
73+
done
74+
75+
- name: Deploy
76+
run: npm run deploy
77+
78+
- name: Check the site (restarts workers if the render bundle is missing)
79+
run: scripts/check-site.sh "${{ vars.SITE_URL }}"

‎README.md‎

Lines changed: 38 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -89,31 +89,53 @@ the app in development and production alike.
8989

9090
## Deploying to Harper Fabric
9191

92-
**CI/CD (the normal path):** every push and pull request runs lint, format check, and
93-
`vite build` (`.github/workflows/ci.yml`); a push to `main` that passes then deploys to
94-
Harper Fabric with `harper deploy`. Configure these secrets on the repo's
95-
`production` environment (Settings → Environments):
96-
97-
- `HARPER_TARGET` — the cluster's Application URL, from its **Config → Overview** page
98-
- `HARPER_CLI_USERNAME` / `HARPER_CLI_PASSWORD` — cluster credentials the CLI
99-
authenticates with (read by `harper deploy` as `HARPER_CLI_*` env vars)
92+
**Production (automatic):** every push and pull request runs lint, format check, and
93+
`vite build` (`.github/workflows/ci.yml`). A push to `main` that passes deploys to the
94+
`production` environment (`.github/workflows/deploy.yml`), then waits for the site to come
95+
back and restarts the HTTP workers if it doesn't (see below).
96+
97+
**Staging (manual):** Actions → **Deploy to staging** → **Run workflow**, with a branch, tag,
98+
or commit (`ref`) or a pull request number (`pr`). It runs the same checks first. A pull
99+
request from a fork runs on staging with staging's secrets, so review it before deploying.
100+
101+
Each GitHub environment (`production`, `staging`; Settings → Environments) needs:
102+
103+
| Kind | Name | Value |
104+
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------- |
105+
| secret | `HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD` | cluster credentials `harper deploy` authenticates with |
106+
| secret | `OAUTH_GITHUB_CLIENT_ID`, `OAUTH_GITHUB_CLIENT_SECRET` | that environment's GitHub OAuth app |
107+
| variable or secret | `HARPER_CLI_TARGET` | the cluster's operations URL, e.g. `https://<host>:9925/` |
108+
| variable | `SITE_URL` | the public origin, e.g. `https://<host>` |
109+
| variable or secret | `OAUTH_REDIRECT_URI` | `<SITE_URL>/oauth/callback` (the plugin appends the provider) |
110+
| variable or secret | `ADMIN_GITHUB_LOGINS` | optional; seed admins, comma-separated |
111+
112+
The app reads its OAuth settings from `.env` (`config.yaml` → `loadEnv`) and `harper deploy`
113+
ships the working directory, so the deploy job writes `.env` from these settings right before
114+
deploying. To load an existing `.env` in one go, run `gh secret set --env <name> -f .env`;
115+
the settings marked "variable or secret" are read from either. Each environment needs its own
116+
GitHub OAuth app, because the callback URL is per domain: `<SITE_URL>/oauth/github/callback`.
100117

101118
**Manually, from a machine:**
102119

103120
```bash
104121
harper login <Application URL> # once; from your cluster's Config → Overview page
105-
npm run deploy # harper deploy project=code-and-learn restart=true
122+
npm run deploy # harper deploy project=code-and-learn restart=true install_allow_scripts=true
106123
```
107124

108-
No build step before deploying: `@harperfast/vite` builds on the node at startup and
109-
rebuilds when watched source changes.
125+
`harper deploy` ships the working directory, **including gitignored files such as `.env`**.
126+
Make sure `.env` holds the target environment's settings and nothing local-only
127+
(`LOCAL_DEV_LOGIN`, `LOCAL_DATA_FILE`, localhost OAuth settings).
110128

111-
Set these runtime environment variables on the cluster (Fabric → application settings):
129+
No build step before deploying: `@harperfast/vite` builds on the node at startup and
130+
rebuilds when watched source changes. If a deploy leaves the site failing with
131+
`ENOENT … node_modules/.harper-vite-ssr/entry-server.js` (the server-side render bundle went
132+
missing), restart the HTTP workers on every node; the CI deploy does this automatically
133+
(`scripts/check-site.sh`). Note that `harper restart` restarts a _local_ instance, not the
134+
cluster.
112135

113-
- `OAUTH_GITHUB_CLIENT_ID` / `OAUTH_GITHUB_CLIENT_SECRET`
114-
- `OAUTH_REDIRECT_URI=https://<your-domain>/oauth/callback` — required in production; the
115-
plugin appends the provider name
116-
- `ADMIN_GITHUB_LOGINS=login1,login2` — seed admins; they can promote others from `/admin`
136+
```bash
137+
npx harper restart_service service=http_workers replicated=true
138+
```
117139

118140
Sessions must be enabled on the instance (`authentication.enableSessions: true` in the
119141
instance's `harper-config.yaml`) for cookie-based OAuth sessions.

‎scripts/check-site.sh‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/usr/bin/env bash
2+
# Post-deploy check: waits for the site to serve pages again.
3+
#
4+
# A fresh deploy sometimes leaves a node serving
5+
# "ENOENT … node_modules/.harper-vite-ssr/entry-server.js": the server-side
6+
# render bundle that @harperfast/vite builds on the node at startup goes
7+
# missing. Restarting the HTTP workers rebuilds it. So: wait for the site; if
8+
# it isn't healthy in time, restart the workers on every node once and wait
9+
# again; fail if it still isn't healthy.
10+
#
11+
# Usage: scripts/check-site.sh <site-url>
12+
# Needs HARPER_CLI_TARGET / HARPER_CLI_USERNAME / HARPER_CLI_PASSWORD for the
13+
# restart.
14+
set -euo pipefail
15+
16+
site="${1:?usage: scripts/check-site.sh <site-url>}"
17+
interval=10
18+
# Responses are load-balanced across nodes, so one good response isn't enough.
19+
needed=3
20+
21+
# Waits up to $1 seconds for $needed consecutive healthy responses.
22+
wait_healthy() {
23+
local deadline=$((SECONDS + $1)) streak=0 last=""
24+
while ((SECONDS < deadline)); do
25+
local body code state
26+
body=$(curl -s -m 15 -H 'Accept: text/html' -w '\n%{http_code}' "$site/" || true)
27+
code=$(tail -n1 <<<"$body")
28+
if [[ "$code" == 200 ]] && ! grep -q 'ENOENT' <<<"$body"; then
29+
state="healthy"
30+
streak=$((streak + 1))
31+
else
32+
state="HTTP ${code:-none}$(grep -q 'ENOENT' <<<"$body" && echo ' (render bundle missing)' || true)"
33+
streak=0
34+
fi
35+
[[ "$state" != "$last" ]] && echo "$(date -u +%H:%M:%S) $site: $state" && last="$state"
36+
((streak >= needed)) && return 0
37+
sleep "$interval"
38+
done
39+
return 1
40+
}
41+
42+
if wait_healthy 90; then
43+
echo "Site is up."
44+
exit 0
45+
fi
46+
47+
echo "Site not healthy after the deploy; restarting the HTTP workers on every node."
48+
npx harper restart_service service=http_workers replicated=true
49+
50+
if wait_healthy 180; then
51+
echo "Site is up after the restart."
52+
exit 0
53+
fi
54+
55+
echo "::error::$site is still not serving pages after a worker restart."
56+
exit 1

0 commit comments

Comments
 (0)