Files
cv/docs/design/specs/v6/spec-v6-github-actions.md
T

26 KiB
Raw Blame History

Spec v6 — GitHub Actions

Parent: specs/v4/spec-v4-deploy-infra.md (the pipeline design this one keeps), specs/v4/spec-v4-live-edit.md (the write path this one re-targets) Status: rev.1 — repo side implemented 2026-10-26 (§7), automated checks pass (§8); the owner-side setup and the first verified run are open (§6). rev.2 2026-10-28 — D16: the Basic-auth file leaves the repository (§7.1); repo side implemented, owner-side secret creation open (§6). rev.2 follow-up 2026-10-28 — the write step's mode corrected 600 → 644 after the first dispatch made the worker-side read visible (§7.1). Supersedes: the CI-host legs of spec-v4-deploy-infra.md — the vars. env surface (§3 "Env surface"), D5's "not added to Gitea Actions secrets", D14's Gitea-only host claim — and the Contents-API status codes recorded in spec-v4-live-edit.md §6.1. Everything else in those specs (D1–D4, D6–D9, D11–D13, the token-safety rules, the Dockge-safety argument) stands unchanged.


1. What moved, and what did not

The repository moves to GitHub. GitHub Actions is the only CI that runs on a GitHub repository, so both pipelines move with it.

Nothing about the site's runtime changed: the same nginx container on the same VPS, served by the same Dockge stack, deployed by the same rsync. The three-job pipeline, the concurrency group, the infra trigger filter, the test-before-touch step and the health probe are ported unchanged.

What does change is one thing the pipeline was never separate from: the repository is the content store. Edit mode commits 12 JSON documents through the nginx /api/content/ proxy into that repository, so moving the repository re-targets the write path, and the write path is the part that needed real changes.

2. Decisions

# Decision Why
D1 GitHub is the primary host for the repository; Gitea is retired. GitHub Actions cannot run on a Gitea repository. A Gitea-primary + GitHub-mirror split would have kept edit mode untouched but would have made every deploy wait for the mirror's sync interval — the deployed site would lag the content the owner just saved.
D2 Site hosting stays: VPS + nginx + Dockge, rsync deploy. The edit-mode security boundary is auth_basic at the nginx /api/content/ proxy (spec-v4-live-edit §6.3). A static host without a server-side proxy removes that boundary, so it removes edit mode.
D3 Site identity stays a CI value: SITE_URL / SITE_NAME as GitHub repository variables, read through the same vars. context. GitHub's variables mechanism is the same feature with the same context name — no YAML change, and public values still do not become secrets (spec-v4-deploy-infra rev.2 reasoning holds).
D4 The runtime write-path values are renamed GITEA_TOKEN / GITEA_CONTENTS_API → CONTENT_API_TOKEN / CONTENT_API_BASE, and the upstream Authorization header becomes Bearer. A name that names a host the system no longer calls is a lie in three files and two docs. token <x> was Gitea's form; Bearer is what the GitHub Contents API documents. vite.config.ts sends the identical form, so dev and production cannot diverge on the one header that decides whether a save authenticates.
D4a The proxy_pass ${CONTENT_API_BASE} construction is not changed. NGINX_ENVSUBST_* runs in the image's entrypoint, which renders the template before nginx parses it. Nginx never sees a variable here: it sees a literal upstream URL, which is why the location-prefix → directive-URI mapping works today and why nginx -t resolves the placeholder host during the config test. Only the value and the header change.
D5 src/i18n/draft.ts learns GitHub's conflict answer: 409 Conflict. The Gitea answers (422 + "does not match", legacy 412) stay handled. Verified against the GitHub REST docs: PUT /repos/{o}/{r}/contents/{path} answers 409 for a stale blob sha, and 422 when sha is missing for an existing file. Without 409 a concurrent edit would be reported as a hard failure and would stop the sequential-PUT sequence — the exact case optimistic concurrency exists to survive.
D5a Non-goal, decided: no retry/backoff for GitHub's secondary rate limits (403/429). The measured shape of this workload — 14 GETs per edit-mode page load, 2–4 PUTs per save — is orders of magnitude under 100 concurrent requests, 900 points/min and 80 content-creating requests/min (GitHub's published secondary limits). Adding backoff would be code for a case the site does not produce. If a real run ever reports it, the retry belongs in saveDraft, not in the caller.
D6 Pipeline shape unchanged: build → generate-resume → deploy, three jobs, same artifacts, same concurrency. Triggers stay narrow (push: master, paths: filter, workflow_dispatch). The split is what makes a content error unable to deploy, and it is proven. Narrow triggers matter more now than they did: the repository is public, and a pull_request trigger would run a fork's YAML on this repo's runner with this repo's secrets.
D7 master stays the deployment branch. No branch protection on master. Edit mode PUTs straight to the target branch (default master). A required-PR protection makes every save fail. Renaming the branch to main would touch edit-session.ts, both workflows, the VPS and four documents for no behavioural gain.
D8 GitHub-hosted runners, public repository. GitHub Actions usage is free for public repositories on standard runners and free for self-hosted runners; a private repository would bill minutes against a monthly quota for a pipeline that installs pnpm twice and renders two PDFs. Accepted consequence: the content JSON and the commit history are public.
D9 .gitea/workflows/ is kept until the first GitHub run is verified, then deleted. Owner's call: see the pipelines run green on GitHub before cutting the old ones. This is a scheduled deletion recorded as an open item (§8), not a compatibility shim — nothing reads them once GitHub is the primary.
D15 The two server-side layout values the workflows hard-coded — the stack directory (5 call sites) and the service/container name dong-site (4 call sites) — become the repository variables STACK_DIR and CONTAINER_NAME; the job that uses each refuses a bad value in its first step. Both describe the server's deployment layout, not repository content — the same class of value as SITE_URL: public, therefore a variable and not a secret. As literals they made a stack rename a multi-file YAML edit plus a docs sweep, and a typo would have rsynced dist/ into the wrong directory or probed the wrong container. CONTAINER_NAME is checked against compose.yaml in the same step, because that one string is used twice over — as a compose service argument and as the docker exec / docker logs target — while the file declaring both lives in this repository. Guarding it first means a bad value fails the way the site-identity check fails: at once, naming the variable and where to set it. Recorded sequence: the owner asked for the path first and the name in the same session, so the name moved too rather than staying a literal.
D16 2026-10-28 (rev.2): the Basic-auth file leaves the repository. deploy/htpasswd is untracked and gitignored; deploy-infra.yml writes it into the stack directory (chmod 644, corrected from 600 — see the §7.1 follow-up) from the repository secret HTPASSWD_CONTENT, before the test step; the file's paths: trigger is dropped. Credential rotation is: regenerate the line (htpasswd -nbB), overwrite the secret, workflow_dispatch — no commit. The repository is public (D8), and the htpasswd line is a user name plus a bcrypt hash — offline-bruteforceable from any clone, forever. A hash is not the plaintext, but it does not have to live in the public archive either; the file has exactly two consumers (the production container's auth_basic_user_file mount and the throwaway test container's mount), both reading it from the stack directory, which the job now guarantees before testing. The containment mirrors the write token's rules (§4): one home, never in the repository, never in the bundle. The value is inlined into a single-quoted shell literal in the ssh script: bcrypt's $2y$… must not reach the remote shell unquoted, and appleboy's envs: mechanism exports values unquoted — so envs: is not used; the htpasswd character set (user name + bcrypt base64) carries no single quote, which makes the quoting exact. The empty-secret case fails the step with a named error rather than writing an empty file nginx would accept.

3. Facts verified during the review (method recorded)

Claim How it was checked
pnpm/setup@v3 is the official GitHub action (github.com/pnpm/setup), and its install input defaults to true Read pnpm/setup's action.yml. This is why the build job has no explicit pnpm install step and why porting it needs no change.
Every other action in both workflows is published on GitHub actions/checkout@v7, actions/cache@v4, actions/upload-artifact@v7, actions/download-artifact@v8, burnett01/rsync-deployments@v9, appleboy/ssh-action@v1.2.0 — Gitea Actions was already fetching these from GitHub.
vars. and secrets. contexts map 1:1 GitHub repository variables / secrets, same context syntax.
concurrency, on.push.paths, workflow_dispatch behave as written GitHub supports all three natively; the [INFERENCE] recorded in spec-v4-deploy-infra.md §4 about paths filtering is closed — GitHub filters branches AND paths literally.
api.github.com answers HTTP/2, so D14 (proxy_http_version 2) survives the move Ran a Node http2 client against https://api.github.com from this machine: ALPN negotiated h2 and a response arrived on the HTTP/2 session (403, unauthenticated).
GitHub Contents API request/response shape equals Gitea's Read the GitHub REST docs for Get repository content and Create or update file contents: ?ref= on GET, branch + blob sha in the PUT body, {content:{sha}} in the response, endpoints must be used serially, no branch creation.
GitHub's conflict status is 409; 422 also answers "sha must be provided" and "endpoint spammed" Same docs page, status-code list.
Secondary rate limits are far above this workload GitHub's published limits: ≤100 concurrent requests, ≤900 points/min (a PUT is 5 points), ≤80 content-generating requests/min and ≤500/hour.
CI minutes are free for public repos and for self-hosted runners GitHub Actions billing docs.
No Gitea-only syntax existed in either workflow Read both files end to end.
dong-nz/cv exists, is public, defaults to master, carries no branch protection, and already holds the same 8 refs as the Gitea remote (same shas) — with no tags and no .github/workflows/ yet GET /repos/dong-nz/cv → private: false, default_branch: "master"; GET /repos/dong-nz/cv/branches → 8 branches, every one protected: false, shas equal to git for-each-ref refs/remotes/origin; GET /repos/dong-nz/cv/tags → empty; GET /contents/.gitea/workflows/deploy.yml?ref=master → 200 while the same path under .github/ → 404, i.e. the migration commit is not pushed yet. Checked 2026-10-26.

4. Env surface (the whole contract)

Value Home Consumers
SITE_URL, SITE_NAME GitHub repository variables (vars.), passed as job env to build and generate-resume the vite site-identity plugin, src/data/site.ts, generate-sitemap.ts, generate-resume.ts
STACK_DIR GitHub repository variables (vars.) — the absolute stack directory as the deploy user sees it, no trailing slash the deploy job's remote_path, the infra job's two remote_paths and its three appleboy/ssh-action scripts; the guard step in each job
CONTAINER_NAME GitHub repository variables (vars.) — the compose service name and the container name, which compose.yaml declares as one and the same the infra job's docker compose up -d --force-recreate, docker exec ×2 and docker logs; the guard step, which greps compose.yaml for both declarations
DEPLOY_HOST, DEPLOY_SSH_PORT, DEPLOY_USER, DEPLOY_SSH_PRIVATE_KEY GitHub secrets the rsync steps, the appleboy/ssh-action steps
HTPASSWD_CONTENT GitHub secret (D16) — the one htpasswd line, user + bcrypt hash the infra job's "Write deploy/htpasswd from the secret" step, which writes ${STACK_DIR}/deploy/htpasswd (chmod 644 — the nginx worker, uid 101, opens auth_basic_user_file per request, so the file must be world-readable; 600 failed on the first dispatch, §7.1 follow-up) before the test container mounts it; the nginx container then serves it as auth_basic_user_file. Locally: an untracked deploy/htpasswd copy, needed by the compose mount
CONTENT_API_TOKEN, CONTENT_API_BASE the stack's single config file secrets/site_config (chmod 600, server-side, never committed, never in CI) the nginx container's envsubst template step; locally the uncommitted .env, read by vite.config.ts
NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN|CONTENT_API_BASE compose.yaml the official entrypoint's template renderer (a regex over variable names; alternatives separated with |)

The token's rules are unchanged from spec-v4-deploy-infra.md §5: single home, least scope (a dedicated restricted write token, now a GitHub fine-grained PAT with Contents: Read and write on this repository only, named site-contents-write, expiring), never in the repository, never in CI secrets, never in the bundle, never printed by the infra workflow. The token's provider changed; its containment did not.

CONTENT_API_BASE is the full Contents-API base including the repository path — for this repository: https://api.github.com/repos/dong-nz/cv/contents/.

STACK_DIR carries no trailing slash because the workflows append /dist/ and / themselves (D16 removed the third append: the auth file is written by the job, not rsynced); the guard rejects a trailing slash so a doubled one cannot reach rsync. CONTAINER_NAME is the single string compose.yaml declares twice — the service key dong-site: and container_name: dong-site — and the infra job uses it in both roles (docker compose up -d --force-recreate <name>, then docker exec / docker logs <name>), so the guard greps the checked-out compose.yaml and refuses a value matching neither. A stack rename is then: change compose.yaml in a commit, change the two variables — and the pipeline names the disagreement if the two are out of step.

5. Migration runbook — the order is part of the design

  1. Push the repository to GitHub (master).
  2. Create the GitHub variables and secrets (§4), and the fine-grained write token.
  3. Update /opt/stacks/dong-site/secrets/site_config on the VPS first — both new names with the GitHub values. This must precede step 4: the migration commit touches nginx.conf and compose.yaml, so the infra workflow runs in the same push, and --force-recreate (D4 of the infra spec) restarts the container with the config the file just supplied. A config file still carrying the old names renders ${CONTENT_API_BASE} unsubstituted, nginx fails to start, the health probe fails, and the site is down until the file is fixed. Nothing else in the sequence has that property.
  4. Merge the migration commit → build + generate-resume + deploy run on GitHub. The live site is untouched by this step: deploy.yml rsyncs dist/ only.
  5. deploy-infra.yml runs in the same push (or by workflow_dispatch): rsync the two infra files, write deploy/htpasswd from the HTPASSWD_CONTENT secret (D16) → nginx -t in a throwaway container with placeholders → recreate → health probe.
  6. Smoke the write path: curl GET and PUT through /api/content/ with the Basic credentials, confirm the commit lands on GitHub and the pipeline deploys it; then one real save from ?edit.
  7. Verify a conflict once: two saves against the same document, or an out-of-band commit to master between a read and a save. The second must report a conflict with a rebase offer, not a failure.
  8. Delete .gitea/workflows/ (D9) and archive the Gitea repository.

6. Open items (owner-side)

  • GitHub repository created, master pushed. Verified 2026-10-26 through the GitHub API (§3): dong-nz/cv, public, default_branch: master, 8 refs at the same shas as the Gitea remote. The migration commit is not pushed yet — .github/workflows/ returns 404 on master there.
  • No branch protection on master — verified: every branch reports protected: false. Standing invariant, not a one-time check: required-PR protection would make every edit-mode save fail (D7).
  • Fine-grained PAT site-contents-write: this repository only, Contents: Read and write, expiry set. Until it exists and is pasted into secrets/site_config, the write path is inert everywhere: the proxy sends an empty Bearer, GitHub answers 401, and the app falls back to the visitor site.
  • VPS /opt/stacks/dong-site/secrets/site_config rewritten with the two new names and the GitHub base, chmod 600 — before the migration commit lands (§5 step 3).
  • Restore - master in both workflow triggers. Both files currently trigger on feature/github-migration (a temporary test trigger, set 2026-10-26); until this is closed, merging into master deploys nothing (D6).
  • Push the tag: git push github v0.0.1 — the mirror carried branches but no tags.
  • Repository variables SITE_URL, SITE_NAME; secrets DEPLOY_HOST, DEPLOY_SSH_PORT, DEPLOY_USER, DEPLOY_SSH_PRIVATE_KEY. Without the variables build fails at the identity check; without the secrets the rsync and recreate steps fail while the infra test-before-touch step still passes.
  • Repository variables STACK_DIR (absolute stack directory, /opt/stacks/dong-site, no trailing slash) and CONTAINER_NAME (dong-site, matching compose.yaml). Both jobs stop at their first step without them.
  • GitHub secret HTPASSWD_CONTENT (D16, 2026-10-28): the current deploy/htpasswd line, verbatim. Without it deploy-infra.yml fails at the write step with a named error; the VPS copy written by the 2026-10-23 runs keeps serving until then. While .gitea/workflows/ still exists (D9), Gitea must carry the same secret plus the STACK_DIR / CONTAINER_NAME variables (§7.1 parity, 2026-10-28): without them the Gitea mirror's guard steps refuse the run. After both hosts have the secret, the public repository no longer carries the bcrypt hash; old clones/commits still do — rotate the editor password if that matters.
  • VPS accepts SSH from GitHub-hosted runners (the old runner may have reached the host from the same machine or LAN; GitHub runners come from GitHub's published IP ranges).
  • First deploy.yml and deploy-infra.yml runs observed green; §5 steps 6–7 verified.
  • Local config renamed (untracked files, done 2026-10-26): .env carries SITE_URL, SITE_NAME, CONTENT_API_BASE with the GitHub base, token still supplied as a shell variable; secrets/site_config carries the two new names with the token left empty. With the old names in either file the local stack cannot render nginx (${CONTENT_API_BASE} stays unsubstituted) and pnpm dev builds no /api/content/ proxy.
  • Gitea repository archived.

7. Repository side — what changed

File Change
.github/workflows/deploy.yml new; port of the Gitea workflow, behaviour identical, permissions: contents: read added to all three jobs; the deploy target is ${{ vars.STACK_DIR }}/dist/ behind a "Check stack directory" step (D15)
.github/workflows/deploy-infra.yml new; port, with the test-before-touch placeholders under the CONTENT_API_* names; five stack paths read ${{ vars.STACK_DIR }}, four docker names read ${{ vars.CONTAINER_NAME }}, all behind one "Check stack variables" step that also greps compose.yaml (D15)
nginx.conf ${CONTENT_API_BASE}, Bearer ${CONTENT_API_TOKEN}, comments state the envsubst-before-parse fact (D4a)
compose.yaml NGINX_ENVSUBST_FILTER: CONTENT_API_TOKEN|CONTENT_API_BASE
vite.config.ts reads CONTENT_API_BASE / CONTENT_API_TOKEN, sends Bearer — the same header the production proxy sends
.env.example the two new names + the base-URL shape
src/i18n/draft.ts isConflict(status, message) accepts 409 alongside 422+"does not match" and 412; comments describe the GitHub contract
scripts/smoke-draft.ts check 14: a stubbed proxy answers 409 with GitHub's body → the document reports conflict with http: 409, the base is refreshed from the branch, the draft survives, the sequence continues to the next document, and rebase() still has a field to resolve
src/data/site.ts doc comment: repository variables, not Gitea Actions variables
AGENTS.md, README.md CI host, env names, GitHub variables/secrets setup
specs/v4/spec-v4-deploy-infra.md, specs/v4/spec-v4-live-edit.md supersession notes pointing here; the v2 and v5 specs are completion records and are left as written
.gitea/workflows/* kept until the first green GitHub run (D9). deploy-infra.yml's test step now carries the CONTENT_API_* names, because the template it validates is the one this repository ships. (Rev.1 note "its stack path stays a literal" is superseded by §7.1: the mirrors were brought to full parity with the GitHub workflows on 2026-10-28)

7.1 rev.2 (2026-10-28) — D16: the Basic-auth file leaves the repository

File Change
deploy/htpasswd git rm --cached — untracked, still on disk locally (the local compose mount needs it); its content moves to the HTPASSWD_CONTENT secret
.gitignore + /deploy/htpasswd, in the deployment/runtime-config block beside .env and secrets/
.github/workflows/deploy-infra.yml paths: drops deploy/htpasswd; the "Sync deploy/htpasswd" rsync step is replaced by "Write deploy/htpasswd from the secret" (appleboy/ssh-action: mkdir -p deploy, single-quoted secret literal → printf → chmod 644, empty secret refused with a named error), placed before the test step whose container mounts the file
.gitea/workflows/deploy-infra.yml same D16 change as the GitHub file
.gitea/workflows/deploy.yml + .gitea/workflows/deploy-infra.yml full parity with the GitHub workflows (owner decision 2026-10-28): permissions: contents: read on every job; the "Check stack directory" / "Check stack variables" guard steps added; the literals /opt/stacks/dong-site (9 call sites) and dong-site (4) replaced by ${{ vars.STACK_DIR }} / ${{ vars.CONTAINER_NAME }}. The only intentional differences left: the header comments naming the mirror, and the guard error text pointing at Gitea's settings path (Settings → Actions → Secrets and Variables → Variables). Owner-side consequence: Gitea must now carry STACK_DIR, CONTAINER_NAME (variables) and HTPASSWD_CONTENT (secret) exactly like GitHub, or the guard steps refuse the run — that was previously avoided by the literals (§7's rev.1 note, superseded)
compose.yaml, nginx.conf untouched — the mount and auth_basic_user_file names are unchanged; only the file's origin moved
AGENTS.md, README.md, compose.override.yaml (comment) trigger list, source-of-truth wording, the secrets table row, and the local-stack step that creates deploy/htpasswd

Repo-side verification 2026-10-28: YAML of both workflows parses; the write step's shell contract was exercised locally (a sample user:$2y$… line through the exact single-quoted printf form round-trips byte-identical, and a line containing $ survives the remote shell unexpanded); git status shows deploy/htpasswd staged as removed while the file stays on disk. Owner-side: create the secret (§6), then the next infra run proves the write → test → recreate chain.

Follow-up 2026-10-28 (first dispatch): chmod 600 → 644. The first workflow_dispatch after the secret existed wrote the file at 600; editing then failed in the nginx error log: open() "/etc/nginx/htpasswd" failed (13: Permission denied). Mechanism: nginx's Basic-auth check runs in the access phase in the worker process — nginx:alpine workers run as the unprivileged nginx user (uid 101), not root — and auth_basic_user_file is opened per request, so the file must be readable by a uid other than the deploy user's. The pipeline could not catch it: nginx -t in both containers and the wget probe run as root, which ignores DAC permissions, and / carries no auth — only a real Basic-auth request reads the file as uid 101. The pre-D16 file reached the VPS via rsync from a git checkout at 644, which is why the same mount had always worked. Fix: both workflows write chmod 644 — the file holds only a bcrypt hash, and 644 is the mode production ran with for the mount's whole life. secrets/site_config stays 600: its only reader is the root-run entrypoint. A stricter 640 + chgrp 101 was considered and rejected: it hard-couples the host file to the image's internal uid. Server-side unblock was chmod 644 on the live file (effective on the next request — a per-request open needs no reload); the next dispatch proves the corrected write.

8. Accepted risks

  • Public repository. Every content document and the whole commit history are public. The Basic-auth proxy still gates writes.
  • No branch protection on master. The safety net stays what it always was: content validation in the build job, so a malformed commit fails the pipeline and the last good deploy stays live.
  • No secondary-rate-limit retry (D5a). A 403/429 from GitHub would surface as a failed document and a resumable partial save — visible, not silent.
  • Firewall dependence. The deploy and infra jobs reach the VPS over SSH from GitHub's runner pool; a host-side firewall tightening its source allow-list breaks deploys, not builds.
  • Two pipelines coexist until D9 is closed. Until .gitea/workflows/ is deleted, a push to master on both hosts deploys twice.