mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
ci: move both pipelines to GitHub Actions (spec-v6)
GitHub becomes the primary repository host; the site keeps its VPS + nginx + Dockge host, the three-job pipeline and the same concurrency, so what moves is the CI host and the write-path target. .github/workflows/{deploy,deploy-infra}.yml are ports of the Gitea files with permissions: contents: read on every job. .gitea/workflows/ stays until the first green GitHub run (D9); its infra test step carries the new template variable names because the template it validates is the one this repository now ships.
The write-path values are renamed GITEA_TOKEN / GITEA_CONTENTS_API -> CONTENT_API_TOKEN / CONTENT_API_BASE and the upstream header becomes Bearer — in nginx.conf, in the compose envsubst filter and in the dev proxy, so dev and production send the identical header (D4). draft.ts learns GitHub's answer to a stale blob sha (409) while keeping the 422 "does not match" and 412 legs; smoke-draft.ts check 14 drives a stubbed proxy that answers 409 with GitHub's body and asserts the conflict refreshes the base, keeps the draft and never stops the save sequence.
Both workflows read the stack directory and the compose service / container name from the STACK_DIR and CONTAINER_NAME repository variables instead of hard-coding them, and each job refuses a missing, relative, trailing-slash or compose-disagreeing value in its first step, before any artifact download or rsync reaches the VPS (D15).
Verified: tsc -b and oxlint pass with no new warnings; validate:content, smoke-draft (14 checks) and smoke-generated-ids (7 checks) pass; both workflows parse, every run/script block passes bash -n with the variables substituted, and the guard refuses every bad value against the real compose.yaml. Owner-side variables, secrets, the write token and the VPS config rewrite stay open in spec-v6 §6.
This commit is contained in:
1 parent
1cfeda7987
commit
cff981c5f3
15 files changed
+568
-83
No files matched your search
+5
-3
@@ -1,4 +1,4 @@
|
|||||||
# Site identity (build-time). In CI these are Gitea Actions variables on the
|
# Site identity (build-time). In CI these are GitHub repository variables on the
|
||||||
# build and resume jobs; locally they live in .env. A production build without
|
# build and resume jobs; locally they live in .env. A production build without
|
||||||
# them fails with an explicit error (src/data/site.ts, vite site-identity plugin).
|
# them fails with an explicit error (src/data/site.ts, vite site-identity plugin).
|
||||||
SITE_URL=
|
SITE_URL=
|
||||||
@@ -6,5 +6,7 @@ SITE_NAME=
|
|||||||
|
|
||||||
# Edit-mode write path (dev only). Production reads both values from the
|
# Edit-mode write path (dev only). Production reads both values from the
|
||||||
# stack's secrets/site_config on the VPS, never from a .env.
|
# stack's secrets/site_config on the VPS, never from a .env.
|
||||||
GITEA_TOKEN=
|
# CONTENT_API_BASE is the full Contents-API base URL, repo path + /contents/ included:
|
||||||
GITEA_CONTENTS_API=
|
# https://api.github.com/repos/<owner>/<repo>/contents/
|
||||||
|
CONTENT_API_TOKEN=
|
||||||
|
CONTENT_API_BASE=
|
||||||
@@ -76,9 +76,9 @@ jobs:
|
|||||||
docker run --rm \
|
docker run --rm \
|
||||||
-v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
|
-v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
|
||||||
-v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \
|
-v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \
|
||||||
-e GITEA_TOKEN=placeholder \
|
-e CONTENT_API_TOKEN=placeholder \
|
||||||
-e GITEA_CONTENTS_API=http://127.0.0.1:1 \
|
-e CONTENT_API_BASE=http://127.0.0.1:1 \
|
||||||
-e 'NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API' \
|
-e 'NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN|CONTENT_API_BASE' \
|
||||||
nginx:alpine nginx -t
|
nginx:alpine nginx -t
|
||||||
|
|
||||||
# Apply + verify (D4): recreate is the same command the Dockge deploy
|
# Apply + verify (D4): recreate is the same command the Dockge deploy
|
||||||
|
|||||||
@@ -0,0 +1,145 @@
|
|||||||
|
name: Redeploy Nginx
|
||||||
|
|
||||||
|
# Infra files only (spec-v4-deploy-infra D1): a change to the nginx template,
|
||||||
|
# the compose definition, or the Basic-auth file redeploys the container —
|
||||||
|
# content commits never do. workflow_dispatch is the token-rotation runbook.
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- feature/github-migration
|
||||||
|
paths:
|
||||||
|
- nginx.conf
|
||||||
|
- compose.yaml
|
||||||
|
- deploy/htpasswd
|
||||||
|
workflow_dispatch:
|
||||||
|
|
||||||
|
concurrency:
|
||||||
|
group: deploy-infra
|
||||||
|
cancel-in-progress: false
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
redeploy:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v7
|
||||||
|
# The stack directory and the container name are the server's deployment layout,
|
||||||
|
# not repository content: both come from repository variables (spec-v6 D15), and
|
||||||
|
# STACK_DIR is the same value `deploy.yml` uses. A missing STACK_DIR would rsync
|
||||||
|
# the three infra files into the remote user's home and then run docker in the
|
||||||
|
# wrong place; a CONTAINER_NAME that disagrees with the service this repository
|
||||||
|
# ships would recreate nothing and probe a container that does not exist. Both are
|
||||||
|
# refused here — before any rsync, before anything reaches the server.
|
||||||
|
- name: Check stack variables
|
||||||
|
env:
|
||||||
|
STACK_DIR: ${{ vars.STACK_DIR }}
|
||||||
|
CONTAINER_NAME: ${{ vars.CONTAINER_NAME }}
|
||||||
|
run: |
|
||||||
|
case "$STACK_DIR" in
|
||||||
|
/*) ;;
|
||||||
|
*)
|
||||||
|
echo "::error::STACK_DIR is not an absolute path — add it as a repository variable (Settings → Secrets and variables → Variables), value: the Dockge stack directory, e.g. /opt/stacks/dong-site"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
case "$STACK_DIR" in
|
||||||
|
*/)
|
||||||
|
echo "::error::STACK_DIR must not end with / — this job appends the slashes it needs"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
# The name is used twice over: as the compose service to recreate, and as the
|
||||||
|
# docker target of the health probe. compose.yaml — this repository — declares
|
||||||
|
# both, so the variable is checked against the file it has to agree with.
|
||||||
|
if ! grep -qE "^ ${CONTAINER_NAME}:" compose.yaml; then
|
||||||
|
echo "::error::CONTAINER_NAME is not a service in compose.yaml — the recreate step names a compose service, so the two must match"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
if ! grep -qF "container_name: ${CONTAINER_NAME}" compose.yaml; then
|
||||||
|
echo "::error::CONTAINER_NAME does not match container_name in compose.yaml — docker exec and docker logs target that name"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
echo "Stack: $STACK_DIR, container: $CONTAINER_NAME"
|
||||||
|
|
||||||
|
# Ship exactly the three triggered files. Never .env, never secrets/ (D6).
|
||||||
|
# The action builds the rsync source as "$GITHUB_WORKSPACE/$path" and passes
|
||||||
|
# it as one argument (entrypoint.sh) — so NO --relative: -R mirrors the whole
|
||||||
|
# absolute workspace path onto the server (run 2026-10-23 created
|
||||||
|
# dong-site/workspace/dong.nguyen/cv/… on the VPS). Plain -avz lands each
|
||||||
|
# file's basename in remote_path; the htpasswd step names deploy/ itself.
|
||||||
|
- name: Sync nginx.conf
|
||||||
|
uses: burnett01/rsync-deployments@v9
|
||||||
|
with:
|
||||||
|
switches: -avz
|
||||||
|
path: nginx.conf
|
||||||
|
remote_path: ${{ vars.STACK_DIR }}/
|
||||||
|
remote_host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
remote_port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
remote_user: ${{ secrets.DEPLOY_USER }}
|
||||||
|
remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
|
- name: Sync compose.yaml
|
||||||
|
uses: burnett01/rsync-deployments@v9
|
||||||
|
with:
|
||||||
|
switches: -avz
|
||||||
|
path: compose.yaml
|
||||||
|
remote_path: ${{ vars.STACK_DIR }}/
|
||||||
|
remote_host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
remote_port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
remote_user: ${{ secrets.DEPLOY_USER }}
|
||||||
|
remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
|
- name: Sync deploy/htpasswd
|
||||||
|
uses: burnett01/rsync-deployments@v9
|
||||||
|
with:
|
||||||
|
switches: -avz
|
||||||
|
path: deploy/htpasswd
|
||||||
|
remote_path: ${{ vars.STACK_DIR }}/deploy/
|
||||||
|
remote_host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
remote_port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
remote_user: ${{ secrets.DEPLOY_USER }}
|
||||||
|
remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
|
|
||||||
|
# Test-before-touch (D3): the throwaway container runs the same entrypoint
|
||||||
|
# render pipeline as production, with placeholder values — nginx -t checks
|
||||||
|
# syntax only, so the real token never enters this container or the job.
|
||||||
|
# A failure here fails the job; the live container keeps serving.
|
||||||
|
# The placeholder must be a resolvable literal IP: a literal hostname in
|
||||||
|
# proxy_pass IS resolved while the config is parsed (spec-v4-deploy-infra §4).
|
||||||
|
- name: Test new config
|
||||||
|
uses: appleboy/ssh-action@v1.2.0
|
||||||
|
with:
|
||||||
|
host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
username: ${{ secrets.DEPLOY_USER }}
|
||||||
|
key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
|
script: |
|
||||||
|
cd "${{ vars.STACK_DIR }}"
|
||||||
|
docker run --rm \
|
||||||
|
-v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
|
||||||
|
-v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \
|
||||||
|
-e CONTENT_API_TOKEN=placeholder \
|
||||||
|
-e CONTENT_API_BASE=http://127.0.0.1:1 \
|
||||||
|
-e 'NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN|CONTENT_API_BASE' \
|
||||||
|
nginx:alpine nginx -t
|
||||||
|
|
||||||
|
# Apply + verify (D4): recreate is the same command the Dockge deploy
|
||||||
|
# button runs, with the service/container names from CONTAINER_NAME — already
|
||||||
|
# checked against compose.yaml above. The health probe uses wget because
|
||||||
|
# nginx:alpine carries no curl; on failure the job prints the container log and
|
||||||
|
# fails.
|
||||||
|
- name: Recreate and probe
|
||||||
|
uses: appleboy/ssh-action@v1.2.0
|
||||||
|
with:
|
||||||
|
host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
username: ${{ secrets.DEPLOY_USER }}
|
||||||
|
key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
|
script: |
|
||||||
|
cd "${{ vars.STACK_DIR }}"
|
||||||
|
docker compose up -d --force-recreate "${{ vars.CONTAINER_NAME }}"
|
||||||
|
sleep 2
|
||||||
|
if ! docker exec "${{ vars.CONTAINER_NAME }}" wget -q -O /dev/null http://127.0.0.1/; then
|
||||||
|
docker logs --tail 50 "${{ vars.CONTAINER_NAME }}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
docker exec "${{ vars.CONTAINER_NAME }}" nginx -t
|
||||||
@@ -0,0 +1,141 @@
|
|||||||
|
name: Deploy Static Site
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- feature/github-migration
|
||||||
|
|
||||||
|
|
||||||
|
concurrency:
|
||||||
|
group: deploy
|
||||||
|
cancel-in-progress: false
|
||||||
|
jobs:
|
||||||
|
build:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
# Site identity (spec-v4-deploy-infra D10/D12, spec-v6 D3): the build and the
|
||||||
|
# resume generator derive every published URL and the page title from these two
|
||||||
|
# values; the build fails loudly when either is missing. They are repository
|
||||||
|
# variables — public values, not secrets.
|
||||||
|
env:
|
||||||
|
SITE_URL: ${{ vars.SITE_URL }}
|
||||||
|
SITE_NAME: ${{ vars.SITE_NAME }}
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v7
|
||||||
|
- uses: pnpm/setup@v3
|
||||||
|
with:
|
||||||
|
cache: true
|
||||||
|
version: ^12.0.0
|
||||||
|
runtime: node@24
|
||||||
|
- run: pnpm tsx scripts/validate-content.ts
|
||||||
|
- run: pnpm build
|
||||||
|
- uses: actions/upload-artifact@v7
|
||||||
|
with:
|
||||||
|
name: static-site
|
||||||
|
path: dist/
|
||||||
|
retention-days: 5
|
||||||
|
|
||||||
|
generate-resume:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: build
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
env:
|
||||||
|
SITE_URL: ${{ vars.SITE_URL }}
|
||||||
|
SITE_NAME: ${{ vars.SITE_NAME }}
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v7
|
||||||
|
- uses: pnpm/setup@v3
|
||||||
|
with:
|
||||||
|
cache: true
|
||||||
|
version: ^12.0.0
|
||||||
|
runtime: node@24
|
||||||
|
|
||||||
|
# Cache Playwright browser — download once, reuse
|
||||||
|
- name: Cache Playwright browser
|
||||||
|
uses: actions/cache@v4
|
||||||
|
with:
|
||||||
|
path: ~/.cache/ms-playwright
|
||||||
|
key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
|
||||||
|
restore-keys: |
|
||||||
|
playwright-${{ runner.os }}-
|
||||||
|
|
||||||
|
- run: pnpm install --frozen-lockfile
|
||||||
|
- run: npx playwright install chromium
|
||||||
|
- run: npx playwright install-deps chromium
|
||||||
|
|
||||||
|
# Generate English version (default)
|
||||||
|
- run: pnpm tsx scripts/generate-resume.ts --lang=en
|
||||||
|
|
||||||
|
# Generate Vietnamese version
|
||||||
|
- run: pnpm tsx scripts/generate-resume.ts --lang=vi
|
||||||
|
|
||||||
|
# Upload both PDF artifacts
|
||||||
|
- uses: actions/upload-artifact@v7
|
||||||
|
with:
|
||||||
|
name: resume-pdf-en
|
||||||
|
path: dist/resume.pdf
|
||||||
|
retention-days: 1
|
||||||
|
|
||||||
|
- uses: actions/upload-artifact@v7
|
||||||
|
with:
|
||||||
|
name: resume-pdf-vi
|
||||||
|
path: dist/resume-vi.pdf
|
||||||
|
retention-days: 1
|
||||||
|
|
||||||
|
deploy:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: [build, generate-resume]
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
steps:
|
||||||
|
# The stack directory is the server's deployment layout, not repository
|
||||||
|
# content: it comes from the STACK_DIR repository variable (spec-v6 D15). An
|
||||||
|
# empty or malformed value would aim rsync at /dist/ on the remote host, so the
|
||||||
|
# job refuses it here — before any artifact download, before anything reaches the
|
||||||
|
# server — exactly like the site-identity check refuses a missing SITE_URL.
|
||||||
|
- name: Check stack directory
|
||||||
|
env:
|
||||||
|
STACK_DIR: ${{ vars.STACK_DIR }}
|
||||||
|
run: |
|
||||||
|
case "$STACK_DIR" in
|
||||||
|
/*) ;;
|
||||||
|
*)
|
||||||
|
echo "::error::STACK_DIR is not an absolute path — add it as a repository variable (Settings → Secrets and variables → Variables), value: the Dockge stack directory, e.g. /opt/stacks/dong-site"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
case "$STACK_DIR" in
|
||||||
|
*/)
|
||||||
|
echo "::error::STACK_DIR must not end with / — this job appends /dist/ itself"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
echo "Deploy target: $STACK_DIR/dist/"
|
||||||
|
- uses: actions/download-artifact@v8
|
||||||
|
with:
|
||||||
|
name: static-site
|
||||||
|
path: dist/
|
||||||
|
|
||||||
|
- uses: actions/download-artifact@v8
|
||||||
|
with:
|
||||||
|
name: resume-pdf-en
|
||||||
|
path: dist/
|
||||||
|
|
||||||
|
- uses: actions/download-artifact@v8
|
||||||
|
with:
|
||||||
|
name: resume-pdf-vi
|
||||||
|
path: dist/
|
||||||
|
|
||||||
|
- name: rsync deployments
|
||||||
|
uses: burnett01/rsync-deployments@v9
|
||||||
|
with:
|
||||||
|
debug: true
|
||||||
|
switches: -avzr --delete
|
||||||
|
path: dist/
|
||||||
|
remote_path: ${{ vars.STACK_DIR }}/dist/
|
||||||
|
remote_host: ${{ secrets.DEPLOY_HOST }}
|
||||||
|
remote_port: ${{ secrets.DEPLOY_SSH_PORT }}
|
||||||
|
remote_user: ${{ secrets.DEPLOY_USER }}
|
||||||
|
remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
|
||||||
@@ -90,14 +90,14 @@ Content is split once, at authoring time, into language-neutral **structure docu
|
|||||||
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, reads the live branch documents the current route needs (see the next bullet), and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview
|
- Entry and persistence: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code) when the query is present **or** the session flag is set. The mode is a session, not a URL state: while it is active every route change re-attaches `?edit` (a replace-navigation in `EditModeShell`), so clicking any link keeps edit mode and a reload reopens it — only the EditBar's Exit returns to the visitor site (it clears the flag, which unmounts the shell, and strips the query). The shell's initialization runs once per mount (entry URL from a ref, `stripEditQuery` reads `window.location`), so navigation never re-authenticates, re-fetches, or re-restores the draft. The shell authenticates, reads the live branch documents the current route needs (see the next bullet), and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview
|
||||||
|
|
||||||
- Document scope (`src/i18n/edit-scope.ts`): the documents a session reads come from the page manifests, never from component code — a claim names a joined record, and an entity owns its structure document plus its two text documents, which are always read as one unit (a half-loaded entity would make the validator compare a live document against a bundled one). Entry = the entry route's scope plus anything a restored draft already touched (those need a real blob sha). A route change reads only the documents still missing — each is adopted through `DraftStore.adoptBase`, which refuses a document the draft has already changed — and the category labels only where a project renders. A document still on its bundled baseline is never PUT over the branch: `saveDraft` sees the empty sha, reads the branch, and hands it to the conflict flow. The bundled copy stays the offline fallback, never a silent substitute for a live read
|
- Document scope (`src/i18n/edit-scope.ts`): the documents a session reads come from the page manifests, never from component code — a claim names a joined record, and an entity owns its structure document plus its two text documents, which are always read as one unit (a half-loaded entity would make the validator compare a live document against a bundled one). Entry = the entry route's scope plus anything a restored draft already touched (those need a real blob sha). A route change reads only the documents still missing — each is adopted through `DraftStore.adoptBase`, which refuses a document the draft has already changed — and the category labels only where a project renders. A document still on its bundled baseline is never PUT over the branch: `saveDraft` sees the empty sha, reads the branch, and hands it to the conflict flow. The bundled copy stays the offline fallback, never a silent substitute for a live read
|
||||||
- Target branch (spec D10): `?edit=<branch>` reads (`?ref=`) and writes (`branch` in the PUT body) that branch; a bare `?edit` resumes the session's last branch, default `master`. Names are validated against git ref rules in `src/i18n/edit-session.ts` before any request (illegal → exit like a failed auth); the branch is stored beside the session flag. The target branch must already exist — Contents API updates never create branches. Only `master` deploys, so the EditBar shows a merge hint on other branches
|
- Target branch (spec D10): `?edit=<branch>` reads (`?ref=`) and writes (`branch` in the PUT body) that branch; a bare `?edit` resumes the session's last branch, default `master`. Names are validated against git ref rules in `src/i18n/edit-session.ts` before any request (illegal → exit like a failed auth); the branch is stored beside the session flag. The target branch must already exist — Contents API updates never create branches. Only `master` deploys, so the EditBar shows a merge hint on other branches. `master` carries **no branch protection**: a required-PR rule would refuse the edit-mode PUT (spec-v6 D7)
|
||||||
- Auth: HTTP Basic at the nginx `/api/content/` proxy is the security boundary; `src/i18n/edit-mode.ts` probes it through a hidden iframe and nothing else. The `?edit` parsing, the session flag `portfolio-edit`, the branch flag and `portfolio-draft` key live in `src/i18n/edit-session.ts` — a module with no imports, because `App.tsx` reads the mode gate from it and must not pull the auth probe (and through it `draft.ts`) into the entry chunk. A failed probe (401 or cancelled prompt) clears the flag and strips `?edit` → normal visitor site
|
- Auth: HTTP Basic at the nginx `/api/content/` proxy is the security boundary; `src/i18n/edit-mode.ts` probes it through a hidden iframe and nothing else. The `?edit` parsing, the session flag `portfolio-edit`, the branch flag and `portfolio-draft` key live in `src/i18n/edit-session.ts` — a module with no imports, because `App.tsx` reads the mode gate from it and must not pull the auth probe (and through it `draft.ts`) into the entry chunk. A failed probe (401 or cancelled prompt) clears the flag and strips `?edit` → normal visitor site
|
||||||
- `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + blob `sha`) of the 12 writable documents (4 structure + 8 text), copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on save conflicts (Gitea 28 reports a blob-sha mismatch as 422 with a "does not match" message; older deployments answered 412 — both are handled; origin / base / working kept separate), draft persisted to sessionStorage `portfolio-draft`, sequential-PUT save (one commit per touched document, resume from the first unwritten one on failure). Edit mode writes JSON only: the id-union leg was deleted when spec-v5 made the unions generated, and the store is handed the branch's category labels (read-only `ui/projects.json` fetches) for rule 7 — `null` when they cannot be read, in which case the rule is skipped and the EditBar says so
|
- `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + blob `sha`) of the 12 writable documents (4 structure + 8 text), copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on save conflicts (GitHub answers a blob-sha mismatch as **409 Conflict**; the Gitea answers — 422 with a "does not match" message, 412 on older deployments — stay handled, `isConflict()` owns the mapping; origin / base / working kept separate), draft persisted to sessionStorage `portfolio-draft`, sequential-PUT save (one commit per touched document, resume from the first unwritten one on failure). Edit mode writes JSON only: the id-union leg was deleted when spec-v5 made the unions generated, and the store is handed the branch's category labels (read-only `ui/projects.json` fetches) for rule 7 — `null` when they cannot be read, in which case the rule is skipped and the EditBar says so
|
||||||
- `src/components/ui/EditableText.tsx` — the site's own element (`as` = the tag or motion component it renders today) becomes the inline editor only in edit mode; commit on blur only (Vietnamese IME-safe), Esc cancels, Enter commits single-line fields, paste is plain-text, empty required values are rejected at commit; without an `EditContext` provider it renders byte-identical markup to the plain element
|
- `src/components/ui/EditableText.tsx` — the site's own element (`as` = the tag or motion component it renders today) becomes the inline editor only in edit mode; commit on blur only (Vietnamese IME-safe), Esc cancels, Enter commits single-line fields, paste is plain-text, empty required values are rejected at commit; without an `EditContext` provider it renders byte-identical markup to the plain element
|
||||||
- `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert and "appears on" page annotations (computed from the page manifests via `manifestsClaiming`, never from component code), conflict resolution (rebase / take-theirs / per-field keep-mine–keep-theirs), per-document save status, partial-save resume, exit confirm
|
- `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert and "appears on" page annotations (computed from the page manifests via `manifestsClaiming`, never from component code), conflict resolution (rebase / take-theirs / per-field keep-mine–keep-theirs), per-document save status, partial-save resume, exit confirm
|
||||||
- Editable surface: content text inline (pencil-triggered, click never edits) **and** structure — chip-level tag editors for every tag array (`technologies`, `metrics`, `skills`, `interests`, `roles`, `keywords`, `responsibilities`, quote details, tagline segments), ghost add/delete/move on every record surface, per-record settings popover (`featured`, the project `category` picker, project section list + type picker, `variant`, location, logo), ids auto-generated from title slugs, social links handle-only with URLs derived in the loaders. Implemented 2026-10-23 (`spec-v4-inline-editing.md` + `spec-v4-data-organization.md`); the JSON panel is deleted. UI documents stay read-only in v4. `category` is a single structure value, not a chip list: the picker offers exactly the label map of `ui/projects.json` — the vocabulary rule 7 checks a project against — so a category with no label in both languages cannot be chosen from the UI; a brand-new category means adding its labels in the repository first. Field provenance: hovering any pencil shows `document → pointer` (`describeField()` names the per-entity file automatically); the EditBar diff line and a `validate:content` error for the same field read identically
|
- Editable surface: content text inline (pencil-triggered, click never edits) **and** structure — chip-level tag editors for every tag array (`technologies`, `metrics`, `skills`, `interests`, `roles`, `keywords`, `responsibilities`, quote details, tagline segments), ghost add/delete/move on every record surface, per-record settings popover (`featured`, the project `category` picker, project section list + type picker, `variant`, location, logo), ids auto-generated from title slugs, social links handle-only with URLs derived in the loaders. Implemented 2026-10-23 (`spec-v4-inline-editing.md` + `spec-v4-data-organization.md`); the JSON panel is deleted. UI documents stay read-only in v4. `category` is a single structure value, not a chip list: the picker offers exactly the label map of `ui/projects.json` — the vocabulary rule 7 checks a project against — so a category with no label in both languages cannot be chosen from the UI; a brand-new category means adding its labels in the repository first. Field provenance: hovering any pencil shows `document → pointer` (`describeField()` names the per-entity file automatically); the EditBar diff line and a `validate:content` error for the same field read identically
|
||||||
- Dev parity: `vite.config.ts` builds the `/api/content/` dev proxy from the same `GITEA_CONTENTS_API` value production nginx renders — run `pnpm dev` with `GITEA_TOKEN` + `GITEA_CONTENTS_API` set (local `.env`); without them edit mode falls to the offline state (bundled content, save disabled)
|
- Dev parity: `vite.config.ts` builds the `/api/content/` dev proxy from the same `CONTENT_API_BASE` value production nginx renders and sends the same `Bearer` header — run `pnpm dev` with `CONTENT_API_TOKEN` + `CONTENT_API_BASE` set (local `.env`); without them edit mode falls to the offline state (bundled content, save disabled)
|
||||||
- Spec: `docs/design/specs/v4/spec-v4-live-edit.md` §5–§6
|
- Spec: `docs/design/specs/v4/spec-v4-live-edit.md` §5–§6; CI host and the write path's provider contract: `docs/design/specs/v6/spec-v6-github-actions.md`
|
||||||
|
|
||||||
## Component Structure
|
## Component Structure
|
||||||
|
|
||||||
@@ -139,20 +139,26 @@ src/
|
|||||||
|
|
||||||
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
||||||
- `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named
|
- `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named
|
||||||
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule, and the scoped-baseline rules of spec-v4-live-edit §5.1 (an adopted baseline replaces an untouched document only; a bundle-seeded document is never PUT over the branch)
|
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule, the scoped-baseline rules of spec-v4-live-edit §5.1 (an adopted baseline replaces an untouched document only; a bundle-seeded document is never PUT over the branch), and the 409 path of spec-v6 D5 (a conflict refreshes the base, keeps the draft, and never stops the sequence)
|
||||||
- `scripts/smoke-generated-ids.ts` — regression check of the generator (`pnpm tsx scripts/smoke-generated-ids.ts`): the shipped module equals the shipped documents, byte-stable output, `never` for emptied documents, malformed documents refused with the file named
|
- `scripts/smoke-generated-ids.ts` — regression check of the generator (`pnpm tsx scripts/smoke-generated-ids.ts`): the shipped module equals the shipped documents, byte-stable output, `never` for emptied documents, malformed documents refused with the file named
|
||||||
|
|
||||||
## Deployment
|
## Deployment
|
||||||
|
|
||||||
- Site deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml` (push to `master`); infra redeployment by `.gitea/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, plus `workflow_dispatch` (the token-rotation runbook): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md`)
|
- Site deployment is triggered automatically by the GitHub workflow `.github/workflows/deploy.yml` (push to `master`); infra redeployment by `.github/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, plus `workflow_dispatch` (the token-rotation runbook): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md` + `docs/design/specs/v6/spec-v6-github-actions.md`)
|
||||||
- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are Gitea Actions **variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable
|
- The repository is GitHub-primary and **public**; `master` is unprotected on purpose (an edit-mode PUT must not be refused). `.gitea/workflows/` stays in the tree until the first green GitHub run is verified, then it is deleted and the Gitea repository is archived (spec-v6 D9)
|
||||||
- Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `/opt/stacks/dong-site/dist/`
|
- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are GitHub **repository variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable
|
||||||
- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Gitea Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec D14; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template still carries only `${GITEA_CONTENTS_API}` / `${GITEA_TOKEN}` — the token and the Gitea host never enter the SPA bundle or the repository)
|
- The stack directory and the container name are deployment-time configuration as well: both workflows read the stack path from the repository variable `STACK_DIR` — absolute, **no trailing slash**, because the jobs append `/dist/`, `/` and `/deploy/` themselves — and the infra job reads the compose service / container name it recreates and probes from `CONTAINER_NAME`. Each job refuses a bad value in its first step, before any artifact download or rsync reaches the VPS, and the infra guard greps `compose.yaml` so `CONTAINER_NAME` cannot disagree with the service and `container_name` this repository declares (spec-v6 D15)
|
||||||
- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `GITEA_TOKEN=` / `GITEA_CONTENTS_API=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml` / `deploy/htpasswd`
|
- Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `${{ vars.STACK_DIR }}/dist/`
|
||||||
|
- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec-v4 D14, verified against `api.github.com` 2026-10-26; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template carries only `${CONTENT_API_BASE}` and `Bearer ${CONTENT_API_TOKEN}` — the token and the git host never enter the SPA bundle or the repository). The image's envsubst step renders the template **before nginx parses it**, so `proxy_pass` is a literal upstream rather than an nginx variable — the reason the location-prefix → directive-URI mapping works and the reason a placeholder in `proxy_pass` must be a resolvable literal IP (spec-v6 D4a)
|
||||||
|
- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `CONTENT_API_TOKEN=` / `CONTENT_API_BASE=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml` / `deploy/htpasswd`
|
||||||
- `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected
|
- `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected
|
||||||
|
|
||||||
```
|
```
|
||||||
.gitea/
|
.github/
|
||||||
|
└── workflows/
|
||||||
|
├── deploy.yml
|
||||||
|
└── deploy-infra.yml
|
||||||
|
.gitea/ # kept until the first green GitHub run (spec-v6 D9)
|
||||||
└── workflows/
|
└── workflows/
|
||||||
├── deploy.yml
|
├── deploy.yml
|
||||||
└── deploy-infra.yml
|
└── deploy-infra.yml
|
||||||
@@ -204,6 +210,7 @@ All specification documents are in `docs/design/`:
|
|||||||
| `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, palette reference, UI enhancements, mobile navigation, nav & CTA enhancements, nav swatch & hamburger, typography, i18n, resume improvements, resume redesign, review fixes) |
|
| `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, palette reference, UI enhancements, mobile navigation, nav & CTA enhancements, nav swatch & hamburger, typography, i18n, resume improvements, resume redesign, review fixes) |
|
||||||
| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending |
|
| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending |
|
||||||
| `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 |
|
| `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 |
|
||||||
|
| `specs/v6/spec-v6-*.md` | v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1 |
|
||||||
|
|
||||||
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Portfolio
|
# Portfolio
|
||||||
|
|
||||||
Personal engineering portfolio — a bilingual (EN/VI) single-page app built with React 19, TypeScript and Vite. All content is data-driven: language-neutral structure documents in `src/data/*.json`, per-language text dictionaries in `src/i18n/locales/`, joined at load. An authenticated edit mode (`?edit`) edits the live site in place and writes the documents back to the git repository through a Gitea Contents API proxy; pushing to `master` deploys through Gitea Actions CI.
|
Personal engineering portfolio — a bilingual (EN/VI) single-page app built with React 19, TypeScript and Vite. All content is data-driven: language-neutral structure documents in `src/data/*.json`, per-language text dictionaries in `src/i18n/locales/`, joined at load. An authenticated edit mode (`?edit`) edits the live site in place and writes the documents back to the git repository through a Contents API proxy; pushing to `master` deploys through GitHub Actions CI.
|
||||||
|
|
||||||
Product and feature specifications: [`docs/design/spec.md`](docs/design/spec.md) and [`docs/design/specs/`](docs/design/).
|
Product and feature specifications: [`docs/design/spec.md`](docs/design/spec.md) and [`docs/design/specs/`](docs/design/).
|
||||||
|
|
||||||
@@ -33,10 +33,10 @@ cp .env.example .env
|
|||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `SITE_URL` | for `pnpm build` | canonical origin — every published absolute URL (meta tags, sitemap, robots, resume links) derives from it. `pnpm dev` falls back to `http://localhost:5173` without it |
|
| `SITE_URL` | for `pnpm build` | canonical origin — every published absolute URL (meta tags, sitemap, robots, resume links) derives from it. `pnpm dev` falls back to `http://localhost:5173` without it |
|
||||||
| `SITE_NAME` | for `pnpm build` | page `<title>` and Open Graph / Twitter meta. Dev fallback: `Portfolio (dev)` |
|
| `SITE_NAME` | for `pnpm build` | page `<title>` and Open Graph / Twitter meta. Dev fallback: `Portfolio (dev)` |
|
||||||
| `GITEA_CONTENTS_API` | optional | full Gitea Contents-API base URL (`…/api/v1/repos/<owner>/<repo>/contents/`). Enables the dev `/api/content/` proxy — the exact mirror of the production nginx location |
|
| `CONTENT_API_BASE` | optional | full Contents-API base URL (`https://api.github.com/repos/<owner>/<repo>/contents/`). Enables the dev `/api/content/` proxy — the exact mirror of the production nginx location |
|
||||||
| `GITEA_TOKEN` | optional | Gitea access token the dev proxy attaches to write requests |
|
| `CONTENT_API_TOKEN` | optional | access token the dev proxy attaches to write requests (`Authorization: Bearer …`, the same form the production proxy sends) |
|
||||||
|
|
||||||
Without the two `GITEA_*` values everything still runs; edit mode is offline (bundled content, save disabled).
|
Without the two `CONTENT_API_*` values everything still runs; edit mode is offline (bundled content, save disabled).
|
||||||
|
|
||||||
### 3. Run
|
### 3. Run
|
||||||
|
|
||||||
@@ -44,7 +44,7 @@ Without the two `GITEA_*` values everything still runs; edit mode is offline (bu
|
|||||||
pnpm dev # http://localhost:5173 with HMR
|
pnpm dev # http://localhost:5173 with HMR
|
||||||
```
|
```
|
||||||
|
|
||||||
Edit mode: open any route with `?edit` (or `?edit=<branch>` to read and write a specific branch; bare `?edit` resumes the last branch, default `master`). In dev the proxy uses `GITEA_TOKEN` directly — no login prompt.
|
Edit mode: open any route with `?edit` (or `?edit=<branch>` to read and write a specific branch; bare `?edit` resumes the last branch, default `master`). In dev the proxy uses `CONTENT_API_TOKEN` directly — no login prompt.
|
||||||
|
|
||||||
### 4. Commands
|
### 4. Commands
|
||||||
|
|
||||||
@@ -75,8 +75,8 @@ To exercise the real serving path — nginx SPA routing, caching, the authentica
|
|||||||
pnpm build
|
pnpm build
|
||||||
mkdir -p secrets
|
mkdir -p secrets
|
||||||
# secrets/site_config — exactly two lines, chmod 600, never committed:
|
# secrets/site_config — exactly two lines, chmod 600, never committed:
|
||||||
# GITEA_TOKEN=<token>
|
# CONTENT_API_TOKEN=<token>
|
||||||
# GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/
|
# CONTENT_API_BASE=https://api.github.com/repos/<owner>/<repo>/contents/
|
||||||
chmod 600 secrets/site_config
|
chmod 600 secrets/site_config
|
||||||
docker network create docker-network # once; compose.yaml joins it
|
docker network create docker-network # once; compose.yaml joins it
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
@@ -84,27 +84,31 @@ docker compose up -d
|
|||||||
|
|
||||||
`compose.yaml` defines no published port (the VPS container is reached through its own fronting); `compose.override.yaml` — auto-merged by `docker compose`, never shipped by the pipeline — publishes the container on the local loopback. Open **`http://127.0.0.1:8081/`** in a browser; `?edit` there asks for HTTP Basic credentials from `deploy/htpasswd`. If 8081 is taken on your machine, change the host port in `compose.override.yaml`. Stop the stack with `docker compose stop`.
|
`compose.yaml` defines no published port (the VPS container is reached through its own fronting); `compose.override.yaml` — auto-merged by `docker compose`, never shipped by the pipeline — publishes the container on the local loopback. Open **`http://127.0.0.1:8081/`** in a browser; `?edit` there asks for HTTP Basic credentials from `deploy/htpasswd`. If 8081 is taken on your machine, change the host port in `compose.override.yaml`. Stop the stack with `docker compose stop`.
|
||||||
|
|
||||||
## Production deployment (Gitea CI)
|
## Production deployment (GitHub Actions)
|
||||||
|
|
||||||
### Pipelines
|
### Pipelines
|
||||||
|
|
||||||
| Workflow | Trigger | What it does |
|
| Workflow | Trigger | What it does |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| [`.gitea/workflows/deploy.yml`](.gitea/workflows/deploy.yml) | push to `master` | `build` (validate content → `pnpm build`) → `generate-resume` (EN + VI PDFs) → `deploy` rsyncs `dist/` (PDFs included) to `/opt/stacks/dong-site/dist/` on the VPS |
|
| [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) | push to `master` | `build` (validate content → `pnpm build`) → `generate-resume` (EN + VI PDFs) → `deploy` rsyncs `dist/` (PDFs included) to `${STACK_DIR}/dist/` on the VPS |
|
||||||
| [`.gitea/workflows/deploy-infra.yml`](.gitea/workflows/deploy-infra.yml) | push to `master` touching `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, or manual dispatch | rsyncs exactly those three files to the stack directory, tests the new config in a throwaway container (`nginx -t`), then `docker compose up -d --force-recreate` + health probe |
|
| [`.github/workflows/deploy-infra.yml`](.github/workflows/deploy-infra.yml) | push to `master` touching `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, or manual dispatch | rsyncs exactly those three files to the stack directory, tests the new config in a throwaway container (`nginx -t`), then `docker compose up -d --force-recreate` + health probe |
|
||||||
|
|
||||||
Only `master` deploys. A content commit never restarts nginx; an infra commit never rebuilds the site. The VPS stack is managed by Dockge (`/opt/stacks/dong-site`); the repository is the single source of truth for the three infra files.
|
Only `master` deploys. A content commit never restarts nginx; an infra commit never rebuilds the site. The VPS stack is managed by Dockge (`/opt/stacks/dong-site`); the repository is the single source of truth for the three infra files.
|
||||||
|
|
||||||
|
The repository is GitHub-primary and public; the pipelines run on GitHub-hosted runners (free for public repositories). `master` carries no branch protection on purpose: edit mode writes straight to it, and the validation step in `build` is what keeps a malformed content commit from deploying. `.gitea/workflows/` is kept only until the first green GitHub run is verified, then deleted (spec-v6 D9).
|
||||||
|
|
||||||
### One-time setup
|
### One-time setup
|
||||||
|
|
||||||
**1. Gitea Actions variables** — Settings → Actions → Variables (repository level):
|
**1. GitHub repository variables** — Settings → Secrets and variables → Actions → **Variables** (repository level):
|
||||||
|
|
||||||
| Name | Value |
|
| Name | Value |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `SITE_URL` | the canonical origin, e.g. `https://cv.example.com` (no trailing slash) |
|
| `SITE_URL` | the canonical origin, e.g. `https://cv.example.com` (no trailing slash) |
|
||||||
| `SITE_NAME` | the page title string |
|
| `SITE_NAME` | the page title string |
|
||||||
|
| `STACK_DIR` | the absolute stack directory on the VPS, e.g. `/opt/stacks/dong-site` — **no trailing slash** |
|
||||||
|
| `CONTAINER_NAME` | the compose service / container name, e.g. `dong-site` — it must match `compose.yaml`, and the infra job checks that it does |
|
||||||
|
|
||||||
These are public values, so they live in the `vars.` context, not secrets (spec-v4-deploy-infra D10/D12, rev.7). A production build without them fails with an error naming the variable.
|
These are public values, so they live in the `vars.` context, not secrets (spec-v4-deploy-infra D10/D12, spec-v6 D3 and D15). A production build without `SITE_URL` / `SITE_NAME` fails with an error naming the variable; both deploy jobs refuse a missing, relative or trailing-slash `STACK_DIR`, and the infra job refuses a `CONTAINER_NAME` that is not the service `compose.yaml` declares. Every check runs as the job's first step, before anything reaches the VPS.
|
||||||
|
|
||||||
**2. Deployment SSH access** — a deploy user on the VPS plus an SSH key.
|
**2. Deployment SSH access** — a deploy user on the VPS plus an SSH key.
|
||||||
|
|
||||||
@@ -131,7 +135,7 @@ ssh gitea-deployer@vps.example.com -p 2222 -i "$HOME\.ssh\gitea_deploy_key" -o I
|
|||||||
Get-Content -Raw "$HOME\.ssh\gitea_deploy_key" # this content becomes DEPLOY_SSH_PRIVATE_KEY
|
Get-Content -Raw "$HOME\.ssh\gitea_deploy_key" # this content becomes DEPLOY_SSH_PRIVATE_KEY
|
||||||
```
|
```
|
||||||
|
|
||||||
Then create Gitea Actions **secrets** — Settings → Actions → Secrets:
|
Then create GitHub Actions **secrets** — Settings → Secrets and variables → Actions → **Secrets**:
|
||||||
|
|
||||||
| Secret | Value |
|
| Secret | Value |
|
||||||
|---|---|
|
|---|---|
|
||||||
@@ -140,7 +144,7 @@ Then create Gitea Actions **secrets** — Settings → Actions → Secrets:
|
|||||||
| `DEPLOY_USER` | `gitea-deployer` |
|
| `DEPLOY_USER` | `gitea-deployer` |
|
||||||
| `DEPLOY_SSH_PRIVATE_KEY` | the private key content |
|
| `DEPLOY_SSH_PRIVATE_KEY` | the private key content |
|
||||||
|
|
||||||
**3. VPS stack config** — in the stack directory `/opt/stacks/dong-site/`, create `secrets/site_config` (chmod 600, exactly the two `KEY=value` lines shown in step 5 above). The token should be a dedicated Gitea **restricted access token** (`site-contents-write`: this repository only, Contents write, with an expiry). The pipeline never rsyncs `secrets/`, so it can never touch this file; it never appears in `docker inspect` or the Dockge env tab.
|
**3. VPS stack config** — in the stack directory `/opt/stacks/dong-site/`, create `secrets/site_config` (chmod 600, exactly the two `KEY=value` lines shown in step 5 above). The token should be a dedicated GitHub **fine-grained PAT** (`site-contents-write`: this repository only, `Contents: Read and write`, with an expiry). The pipeline never rsyncs `secrets/`, so it can never touch this file; it never appears in `docker inspect` or the Dockge env tab.
|
||||||
|
|
||||||
**4. Edit-mode login** — production `/api/content/` sits behind HTTP Basic (`auth_basic` + `deploy/htpasswd`, committed as hashes). The browser prompts once per session.
|
**4. Edit-mode login** — production `/api/content/` sits behind HTTP Basic (`auth_basic` + `deploy/htpasswd`, committed as hashes). The browser prompts once per session.
|
||||||
|
|
||||||
@@ -148,6 +152,6 @@ Then create Gitea Actions **secrets** — Settings → Actions → Secrets:
|
|||||||
|
|
||||||
Open `https://<SITE_URL>/any-route?edit` (append `=<branch>` to target another branch — it must already exist; the edit UI never creates branches). Edits preview live; saving writes each touched document as its own commit through the proxy, and merging that branch into `master` deploys it via `deploy.yml`.
|
Open `https://<SITE_URL>/any-route?edit` (append `=<branch>` to target another branch — it must already exist; the edit UI never creates branches). Edits preview live; saving writes each touched document as its own commit through the proxy, and merging that branch into `master` deploys it via `deploy.yml`.
|
||||||
|
|
||||||
## Spec status (v4)
|
## Spec status
|
||||||
|
|
||||||
Implemented: locale dictionaries + page manifests (`spec-v4-data-organization.md`), inline editing on every record surface (`spec-v4-inline-editing.md`), live edit + save pipeline (`spec-v4-live-edit.md`), CI pipelines + env-driven site identity (`spec-v4-deploy-infra.md`, rev.7). Remaining owner-side steps are tracked in each spec's Progress Tracking section.
|
Implemented: locale dictionaries + page manifests (`spec-v4-data-organization.md`), inline editing on every record surface (`spec-v4-inline-editing.md`), live edit + save pipeline (`spec-v4-live-edit.md`), CI pipelines + env-driven site identity (`spec-v4-deploy-infra.md`, rev.7), GitHub Actions CI with the GitHub-backed write path (`spec-v6-github-actions.md`). Remaining owner-side steps are tracked in each spec's Progress Tracking section.
|
||||||
+5
-4
@@ -10,8 +10,9 @@ services:
|
|||||||
# Source the config file, then hand over to the image's official entrypoint.
|
# Source the config file, then hand over to the image's official entrypoint.
|
||||||
# set -a is REQUIRED: a sourced assignment is a shell variable, not an env var —
|
# set -a is REQUIRED: a sourced assignment is a shell variable, not an env var —
|
||||||
# without export the entrypoint child (and its envsubst step) sees nothing and
|
# without export the entrypoint child (and its envsubst step) sees nothing and
|
||||||
# the template renders unsubstituted (reproduced locally 2026-10-23: unknown
|
# the template renders unsubstituted (reproduced locally 2026-10-23 as an
|
||||||
# "gitea_contents_api" variable). The nginx command is inline: a compose
|
# "unknown variable" failure; the names are content_api_* since spec-v6). The
|
||||||
|
# nginx command is inline: a compose
|
||||||
# entrypoint override does NOT keep the image's CMD (CMD=[]) — an empty "$@"
|
# entrypoint override does NOT keep the image's CMD (CMD=[]) — an empty "$@"
|
||||||
# makes the exec a no-op, exit 0, restart loop.
|
# makes the exec a no-op, exit 0, restart loop.
|
||||||
entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"]
|
entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"]
|
||||||
@@ -20,9 +21,9 @@ services:
|
|||||||
# REGEX the official entrypoint matches against each variable name
|
# REGEX the official entrypoint matches against each variable name
|
||||||
# (`t ~ /^(filter)$/`) — alternatives MUST be separated with |, a comma
|
# (`t ~ /^(filter)$/`) — alternatives MUST be separated with |, a comma
|
||||||
# matches nothing and leaves ${…} in the rendered config (nginx -t then
|
# matches nothing and leaves ${…} in the rendered config (nginx -t then
|
||||||
# fails: unknown "gitea_contents_api" variable — reproduced 2026-10-23).
|
# fails with an unknown variable — reproduced 2026-10-23).
|
||||||
# $uri/$host stay nginx runtime variables. The filter is not sensitive.
|
# $uri/$host stay nginx runtime variables. The filter is not sensitive.
|
||||||
NGINX_ENVSUBST_FILTER: GITEA_TOKEN|GITEA_CONTENTS_API
|
NGINX_ENVSUBST_FILTER: CONTENT_API_TOKEN|CONTENT_API_BASE
|
||||||
volumes:
|
volumes:
|
||||||
- ./dist:/usr/share/nginx/html:ro
|
- ./dist:/usr/share/nginx/html:ro
|
||||||
# Mounted as a template: the image's envsubst step renders it to
|
# Mounted as a template: the image's envsubst step renders it to
|
||||||
|
|||||||
@@ -2,6 +2,8 @@
|
|||||||
|
|
||||||
Status: **Design agreed 2026-10-23 (rev.8); repo side implemented 2026-10-23; owner-side setup + first verified run TODO.** Closes the manual half of `spec-v4-live-edit.md` §12 row 11 (the infra files ship with a dedicated pipeline), and per the owner's direction of 2026-10-23 removes explicit site identity (`cv.vugado.com`, `code.vugado.com`, repo path, site name) from the repository — those values become deployment-time configuration (D10–D12). Rev.2 added the Dockge reality (D7, D8); rev.3 recorded the owner's confirmed facts (`DOCKGE_STACKS_DIR=/opt/stacks`, upstream Dockge, `compose.yaml` naming) and the matching repository rename (D9, done); rev.4 added the site-identity externalization design (D10–D12); rev.5 moved `GITEA_TOKEN` off the stack `.env` to a Docker secret file after the owner verified file-based secrets work on the VPS's `docker compose` (non-swarm); rev.6 removes the stack `.env` entirely (owner: "don't use .env") — both server-side values live in ONE file, `secrets/site_config` (D13); rev.7 switches the site-identity channel from Gitea Actions secrets to Actions variables (`vars.` context — public values; owner direction 2026-10-23, `deploy.yml` job env updated); rev.8 records the first-run fixes proven by the 2026-10-23 runs and a local reproduction of the test step: three single-path rsync steps, `-R` dropped (the action prefixes `$GITHUB_WORKSPACE`), `NGINX_ENVSUBST_FILTER` as a `|`-regex (a comma form matches nothing), and a resolvable test placeholder (`http://127.0.0.1:1`) — the reproduced test step passes. Implementation landed the same day: `deploy-infra.yml`, the §4.1 `compose.yaml`, `site.ts` env read, the vite site-identity plugin + env-driven dev proxy, generated `robots.txt`, `deploy.yml` job env, `.env.example`, AGENTS.md — see §8 for what remains owner-side.
|
Status: **Design agreed 2026-10-23 (rev.8); repo side implemented 2026-10-23; owner-side setup + first verified run TODO.** Closes the manual half of `spec-v4-live-edit.md` §12 row 11 (the infra files ship with a dedicated pipeline), and per the owner's direction of 2026-10-23 removes explicit site identity (`cv.vugado.com`, `code.vugado.com`, repo path, site name) from the repository — those values become deployment-time configuration (D10–D12). Rev.2 added the Dockge reality (D7, D8); rev.3 recorded the owner's confirmed facts (`DOCKGE_STACKS_DIR=/opt/stacks`, upstream Dockge, `compose.yaml` naming) and the matching repository rename (D9, done); rev.4 added the site-identity externalization design (D10–D12); rev.5 moved `GITEA_TOKEN` off the stack `.env` to a Docker secret file after the owner verified file-based secrets work on the VPS's `docker compose` (non-swarm); rev.6 removes the stack `.env` entirely (owner: "don't use .env") — both server-side values live in ONE file, `secrets/site_config` (D13); rev.7 switches the site-identity channel from Gitea Actions secrets to Actions variables (`vars.` context — public values; owner direction 2026-10-23, `deploy.yml` job env updated); rev.8 records the first-run fixes proven by the 2026-10-23 runs and a local reproduction of the test step: three single-path rsync steps, `-R` dropped (the action prefixes `$GITHUB_WORKSPACE`), `NGINX_ENVSUBST_FILTER` as a `|`-regex (a comma form matches nothing), and a resolvable test placeholder (`http://127.0.0.1:1`) — the reproduced test step passes. Implementation landed the same day: `deploy-infra.yml`, the §4.1 `compose.yaml`, `site.ts` env read, the vite site-identity plugin + env-driven dev proxy, generated `robots.txt`, `deploy.yml` job env, `.env.example`, AGENTS.md — see §8 for what remains owner-side.
|
||||||
|
|
||||||
|
> **Superseded in part on 2026-10-26 by `specs/v6/spec-v6-github-actions.md`:** the CI host is GitHub Actions, `SITE_URL` / `SITE_NAME` are GitHub repository variables, and the write-path values are `CONTENT_API_TOKEN` / `CONTENT_API_BASE` — the `GITEA_*` names throughout this document are what was in force when it was written (rev.7's channel decision, variables not secrets, carries over unchanged; only the host changes). D1–D4, D6–D9, D11–D13, the token-safety rules of §5 and the Dockge-safety argument stand as written; D14's HTTP/2 upstream was re-verified against `api.github.com` and stands.
|
||||||
|
|
||||||
## 1. Current state
|
## 1. Current state
|
||||||
|
|
||||||
- `deploy.yml` ships `dist/` by rsync to `/opt/stacks/dong-site/dist/` on the VPS. The live container `dong-site` (compose at `/opt/stacks/dong-site/compose.yaml`) mounts `./dist`, `./nginx.conf` as an envsubst **template**, and `./deploy/htpasswd`.
|
- `deploy.yml` ships `dist/` by rsync to `/opt/stacks/dong-site/dist/` on the VPS. The live container `dong-site` (compose at `/opt/stacks/dong-site/compose.yaml`) mounts `./dist`, `./nginx.conf` as an envsubst **template**, and `./deploy/htpasswd`.
|
||||||
|
|||||||
@@ -3,6 +3,8 @@
|
|||||||
> **Parent:** `spec.md` (product vision), `specs/v3/spec-v3-i18n.md` (supersedes its Phase 2)
|
> **Parent:** `spec.md` (product vision), `specs/v3/spec-v3-i18n.md` (supersedes its Phase 2)
|
||||||
> **Status:** rev.4 — Phases 1–3 implemented 2026-10-22 (see §12 rows 3–15). Remaining (2026-10-23): the owner-side infra setup + first verified run per `spec-v4-deploy-infra.md` rev.7 (Gitea Actions variables `SITE_URL`/`SITE_NAME`, stack `secrets/site_config` with the restricted `GITEA_TOKEN`), and the owner's browser walkthrough. Content documents are pushed and on `master` (§12 row 11); the production nginx step (§6.3) is automated repo-side by `deploy-infra.yml`.
|
> **Status:** rev.4 — Phases 1–3 implemented 2026-10-22 (see §12 rows 3–15). Remaining (2026-10-23): the owner-side infra setup + first verified run per `spec-v4-deploy-infra.md` rev.7 (Gitea Actions variables `SITE_URL`/`SITE_NAME`, stack `secrets/site_config` with the restricted `GITEA_TOKEN`), and the owner's browser walkthrough. Content documents are pushed and on `master` (§12 row 11); the production nginx step (§6.3) is automated repo-side by `deploy-infra.yml`.
|
||||||
|
|
||||||
|
> **Amended on 2026-10-26 by `specs/v6/spec-v6-github-actions.md`:** the content repository is GitHub-hosted and both pipelines run on GitHub Actions. §6.1's status codes describe the Gitea answers live when this spec was written — GitHub answers a stale blob sha as **409 Conflict**, and 422 "sha must be provided" when the sha is missing for an existing file; `draft.ts` handles all three. The write path's shape is identical on both providers (`?ref=`, `branch` in the PUT body, blob-sha concurrency, sequential PUTs, no branch creation), and §6.3's Basic-auth proxy remains the security boundary.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|||||||
@@ -0,0 +1,116 @@
|
|||||||
|
# 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).
|
||||||
|
> **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. |
|
||||||
|
|
||||||
|
## 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 three `remote_path`s and both `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 step, both `appleboy/ssh-action` steps |
|
||||||
|
| `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 `/deploy/` themselves; 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 three infra files → `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)
|
||||||
|
|
||||||
|
- [x] 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.
|
||||||
|
- [x] 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.
|
||||||
|
- [ ] 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.
|
||||||
|
- [x] 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; its stack path stays a literal — no `STACK_DIR` is created on Gitea for files that are scheduled for deletion |
|
||||||
|
|
||||||
|
## 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.
|
||||||
+18
-14
@@ -39,27 +39,31 @@ server {
|
|||||||
log_not_found off;
|
log_not_found off;
|
||||||
}
|
}
|
||||||
|
|
||||||
# Content write path (spec-v4 §6.2, spec-v4-deploy-infra D11/D13): Basic-auth
|
# Content write path (spec-v4 §6.2, spec-v4-deploy-infra D11/D13, spec-v6 D4):
|
||||||
# at the proxy; ${GITEA_TOKEN} and ${GITEA_CONTENTS_API} are substituted by
|
# Basic-auth at the proxy; ${CONTENT_API_TOKEN} and ${CONTENT_API_BASE} are
|
||||||
# the image's envsubst template step from the container environment (sourced
|
# substituted by the image's envsubst template step from the container
|
||||||
# from the stack's secrets/site_config) — the SPA bundle and the repository
|
# environment (sourced from the stack's secrets/site_config) BEFORE nginx parses
|
||||||
# never carry the token or the Gitea host.
|
# this file — so proxy_pass below is a literal upstream once rendered, exactly as
|
||||||
|
# it was when the URL was written here. The SPA bundle and the repository never
|
||||||
|
# carry the token or the git host.
|
||||||
location /api/content/ {
|
location /api/content/ {
|
||||||
auth_basic "Editor";
|
auth_basic "Editor";
|
||||||
auth_basic_user_file /etc/nginx/htpasswd;
|
auth_basic_user_file /etc/nginx/htpasswd;
|
||||||
|
|
||||||
# HTTP/2 to the upstream (nginx >= 1.29.4; the stack runs 1.31.x). The
|
# HTTP/2 to the upstream (nginx >= 1.29.4; the stack runs 1.31.x; the API host
|
||||||
# edit-mode client issues its 12 document reads + 2 label reads as one
|
# answers an h2 ALPN handshake — verified against api.github.com 2026-10-26). The
|
||||||
# concurrent wave, and the Gitea host answers h2, so those requests
|
# edit-mode client issues its 12 document reads + 2 label reads as one concurrent
|
||||||
# multiplex over a single upstream connection instead of one HTTP/1.1
|
# wave, so those requests multiplex over a single upstream connection instead of
|
||||||
# connection each. Upstream keepalive caching is already the default
|
# one HTTP/1.1 connection each. Upstream keepalive caching is already the default
|
||||||
# since 1.29.7; the docs still require the Connection header to be
|
# since 1.29.7; the docs still require the Connection header to be cleared for a
|
||||||
# cleared for a reused upstream connection.
|
# reused upstream connection.
|
||||||
proxy_http_version 2;
|
proxy_http_version 2;
|
||||||
proxy_set_header Connection "";
|
proxy_set_header Connection "";
|
||||||
|
|
||||||
proxy_pass ${GITEA_CONTENTS_API};
|
proxy_pass ${CONTENT_API_BASE};
|
||||||
proxy_ssl_server_name on;
|
proxy_ssl_server_name on;
|
||||||
proxy_set_header Authorization "token ${GITEA_TOKEN}";
|
# Bearer is the form the GitHub Contents API documents; the legacy "token"
|
||||||
|
# prefix was Gitea's.
|
||||||
|
proxy_set_header Authorization "Bearer ${CONTENT_API_TOKEN}";
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
+52
-4
@@ -5,9 +5,9 @@
|
|||||||
// writes, record add/delete/rename, conflicts and rebase, the validator rules
|
// writes, record add/delete/rename, conflicts and rebase, the validator rules
|
||||||
// a rejected edit is reported through, and the scoped-baseline rules of
|
// a rejected edit is reported through, and the scoped-baseline rules of
|
||||||
// spec-v4-live-edit §5.1 (adoptBase, and a save that must not PUT a
|
// spec-v4-live-edit §5.1 (adoptBase, and a save that must not PUT a
|
||||||
// bundle-seeded document).
|
// bundle-seeded document), and the Contents API conflict answer of spec-v6 D5.
|
||||||
// Run: pnpm tsx scripts/smoke-draft.ts
|
// Run: pnpm tsx scripts/smoke-draft.ts
|
||||||
import { DraftStore, bundledBase, saveDraft } from '../src/i18n/draft';
|
import { DraftStore, bundledBase, PROXY_BASE, saveDraft } from '../src/i18n/draft';
|
||||||
import type { CategoryLabels } from '../src/i18n/validate';
|
import type { CategoryLabels } from '../src/i18n/validate';
|
||||||
import type { DocBase } from '../src/i18n/draft';
|
import type { DocBase } from '../src/i18n/draft';
|
||||||
import projectsEnUiJson from '../src/i18n/locales/en/ui/projects.json';
|
import projectsEnUiJson from '../src/i18n/locales/en/ui/projects.json';
|
||||||
@@ -190,7 +190,7 @@ if ((store8.dataOf('profile.vi') as Record<string, unknown>).bio !== 'KEEP MINE'
|
|||||||
fail('a late read replaced drafted work');
|
fail('a late read replaced drafted work');
|
||||||
|
|
||||||
// 13. A baseline that came from the bundle carries no blob sha, so the save
|
// 13. A baseline that came from the bundle carries no blob sha, so the save
|
||||||
// pipeline must not PUT it over the branch (Gitea reads an empty sha as a
|
// pipeline must not PUT it over the branch (the API reads an empty sha as a
|
||||||
// create). It reads the branch first — with no proxy reachable here that read
|
// create). It reads the branch first — with no proxy reachable here that read
|
||||||
// fails, so the document reports a failure, the save stops before any write,
|
// fails, so the document reports a failure, the save stops before any write,
|
||||||
// and the draft survives.
|
// and the draft survives.
|
||||||
@@ -208,4 +208,52 @@ if (saveProbe.results.length !== 1) fail('the save kept going past the stopped d
|
|||||||
if ((store9.dataOf('profile.vi') as Record<string, unknown>).bio !== 'SCOPED BASELINE')
|
if ((store9.dataOf('profile.vi') as Record<string, unknown>).bio !== 'SCOPED BASELINE')
|
||||||
fail('a failed save lost the draft');
|
fail('a failed save lost the draft');
|
||||||
|
|
||||||
console.log('draft store smoke: all 13 checks passed');
|
// 14. A blob-sha conflict belongs to the conflict flow, not to a hard stop.
|
||||||
|
// GitHub answers 409 Conflict with a body the Gitea-era message matcher would
|
||||||
|
// not recognise — the status alone must drive the flow: refresh that document's
|
||||||
|
// base from the branch, report a conflict, and keep the sequence going.
|
||||||
|
const store10 = new DraftStore(structuredClone(bases), LABELS);
|
||||||
|
for (const id of ['profile.vi', 'profile.en'] as const) {
|
||||||
|
const branchCopy = structuredClone(bases[id]);
|
||||||
|
branchCopy.sha = `branch-${id}`;
|
||||||
|
store10.resetBase(id, branchCopy);
|
||||||
|
}
|
||||||
|
if (store10.setValue('vi', 'profile.bio', 'CONFLICT MINE') !== null)
|
||||||
|
fail('the conflict-probe edit was rejected');
|
||||||
|
if (store10.setValue('en', 'profile.bio', 'CONFLICT MINE EN') !== null)
|
||||||
|
fail('the second conflict-probe edit was rejected');
|
||||||
|
|
||||||
|
const branchDoc = (id: 'profile.vi' | 'profile.en', bio: string) => {
|
||||||
|
const data = structuredClone(bases[id].data) as Record<string, unknown>;
|
||||||
|
data.bio = bio;
|
||||||
|
return { encoded: Buffer.from(JSON.stringify(data, null, 2)).toString('base64'), sha: `moved-${id}` };
|
||||||
|
};
|
||||||
|
const viBranch = branchDoc('profile.vi', 'THEIR BIO');
|
||||||
|
const enBranch = branchDoc('profile.en', 'THEIR BIO EN');
|
||||||
|
|
||||||
|
const realFetch = globalThis.fetch;
|
||||||
|
globalThis.fetch = (async (input: unknown, init?: { method?: string }) => {
|
||||||
|
const url = String(input);
|
||||||
|
if (!url.startsWith(PROXY_BASE)) fail(`the save left the proxy: ${url}`);
|
||||||
|
const branch = url.includes('/vi/content/') ? viBranch : enBranch;
|
||||||
|
if ((init?.method ?? 'GET') === 'PUT')
|
||||||
|
return new Response(JSON.stringify({ message: 'Conflict', documentation_url: 'https://docs.github.com/rest' }), { status: 409 });
|
||||||
|
return new Response(JSON.stringify({ content: branch.encoded, sha: branch.sha }), { status: 200 });
|
||||||
|
}) as unknown as typeof fetch;
|
||||||
|
|
||||||
|
const conflictSave = await saveDraft(store10, () => {}, 'master');
|
||||||
|
globalThis.fetch = realFetch;
|
||||||
|
if (conflictSave.results.length !== 2)
|
||||||
|
fail(`a 409 cut the save short: ${JSON.stringify(conflictSave.results)}`);
|
||||||
|
if (!conflictSave.results.every((r) => r.status === 'conflict' && r.http === 409))
|
||||||
|
fail(`a 409 was not reported as a conflict: ${JSON.stringify(conflictSave.results)}`);
|
||||||
|
if (conflictSave.stoppedEarly) fail('a conflict stopped the save sequence');
|
||||||
|
if (store10.shaOf('profile.vi') !== 'moved-profile.vi') fail('the conflict did not refresh the base from the branch');
|
||||||
|
if (store10.shaOf('profile.en') !== 'moved-profile.en') fail('the second conflict did not refresh its base');
|
||||||
|
if ((store10.dataOf('profile.vi') as Record<string, unknown>).bio !== 'CONFLICT MINE')
|
||||||
|
fail('a conflict dropped the draft');
|
||||||
|
// The refreshed base is what the conflict UI resolves against: my path and the
|
||||||
|
// branch path both moved, so the store must hand the field over, not pick a side.
|
||||||
|
if (store10.rebase('profile.vi') === null) fail('a 409 left nothing for the conflict UI to resolve');
|
||||||
|
|
||||||
|
console.log('draft store smoke: all 14 checks passed');
|
||||||
+3
-3
@@ -1,8 +1,8 @@
|
|||||||
/**
|
/**
|
||||||
* Site identity — deployment-time configuration, not a repository literal
|
* Site identity — deployment-time configuration, not a repository literal
|
||||||
* (spec-v4-deploy-infra D10/D12). CI supplies SITE_URL / SITE_NAME as Gitea
|
* (spec-v4-deploy-infra D10/D12, spec-v6 D3). CI supplies SITE_URL / SITE_NAME
|
||||||
* Actions variables on the build and resume jobs; local runs read them from the
|
* as repository variables on the build and resume jobs; local runs read them from
|
||||||
* uncommitted `.env` (see `.env.example`). A missing value fails loudly — a
|
* the uncommitted `.env` (see `.env.example`). A missing value fails loudly — a
|
||||||
* half-configured sitemap, meta block or resume is never emitted.
|
* half-configured sitemap, meta block or resume is never emitted.
|
||||||
*
|
*
|
||||||
* Browser code does not import this module today; the scripts
|
* Browser code does not import this module today; the scripts
|
||||||
|
|||||||
+28
-18
@@ -217,9 +217,9 @@ function encodeBase64(text: string): string {
|
|||||||
export async function fetchDoc(file: string, branch: string): Promise<DocBase> {
|
export async function fetchDoc(file: string, branch: string): Promise<DocBase> {
|
||||||
const res = await fetch(proxyUrl(file, branch));
|
const res = await fetch(proxyUrl(file, branch));
|
||||||
if (!res.ok) throw new Error(`GET ${file}: ${res.status}`);
|
if (!res.ok) throw new Error(`GET ${file}: ${res.status}`);
|
||||||
// The contents response carries both the blob sha (`sha`) and the last
|
// The contents response carries the blob sha (`sha`) — the same field the
|
||||||
// commit that touched the file (`last_commit_sha`). Gitea 28's UpdateFile
|
// Contents API concurrency check wants, on GitHub and on Gitea alike — and the
|
||||||
// concurrency field is the blob sha — that is the value the draft keeps.
|
// last commit that touched the file. The draft keeps the blob sha.
|
||||||
const json = (await res.json()) as { content?: string; sha?: string };
|
const json = (await res.json()) as { content?: string; sha?: string };
|
||||||
return {
|
return {
|
||||||
data: JSON.parse(decodeBase64(json.content ?? '')),
|
data: JSON.parse(decodeBase64(json.content ?? '')),
|
||||||
@@ -238,10 +238,10 @@ async function putBase64(
|
|||||||
blobSha: string,
|
blobSha: string,
|
||||||
branch: string,
|
branch: string,
|
||||||
): Promise<PutResult> {
|
): Promise<PutResult> {
|
||||||
// Gitea 28 UpdateFileOptions: `sha` is the blob ID of the file to update —
|
// UpdateFileOptions: `sha` is the blob ID of the file to update — empty means
|
||||||
// empty means create (an existing file then answers 422 "repository file
|
// create (an existing file then refuses it), a stale one is a concurrency
|
||||||
// already exists"), a stale one means a concurrency mismatch. The FileResponse
|
// mismatch: GitHub answers 409 Conflict, Gitea 28 answered 422 with a "does not
|
||||||
// returns the new blob sha at `content.sha`.
|
// match" message. The response carries the new blob sha at `content.sha`.
|
||||||
const res = await fetch(proxyUrl(file, branch), {
|
const res = await fetch(proxyUrl(file, branch), {
|
||||||
method: 'PUT',
|
method: 'PUT',
|
||||||
headers: { 'content-type': 'application/json' },
|
headers: { 'content-type': 'application/json' },
|
||||||
@@ -267,7 +267,7 @@ async function putBase64(
|
|||||||
}
|
}
|
||||||
|
|
||||||
// Serialize exactly as the repository file is formatted (2-space indent, key
|
// Serialize exactly as the repository file is formatted (2-space indent, key
|
||||||
// order preserved from the parsed document) so Gitea diffs stay reviewable
|
// order preserved from the parsed document) so repository diffs stay reviewable
|
||||||
// (§6.1).
|
// (§6.1).
|
||||||
export function putDoc(
|
export function putDoc(
|
||||||
file: string,
|
file: string,
|
||||||
@@ -985,12 +985,21 @@ export type DocSaveResult = {
|
|||||||
http?: number;
|
http?: number;
|
||||||
};
|
};
|
||||||
|
|
||||||
// Sequential PUTs, one commit per touched document (§6.1). A blob-sha
|
// The Contents API's answer to a stale blob sha: GitHub 409 Conflict, Gitea 28
|
||||||
// mismatch — Gitea 28 answers 422 with a "does not match" message, older
|
// 422 with a "does not match" message, older deployments 412. All three mean the
|
||||||
// deployments answered 412 — refreshes that document's base and reports a
|
// branch moved under this document — the conflict flow resolves it (§5.6).
|
||||||
// conflict without stopping the sequence; any other failure stops so a retry
|
function isConflict(status: number, message: string): boolean {
|
||||||
// resumes from the first unwritten document — landed documents are never
|
return (
|
||||||
// rewritten (§5.6).
|
status === 409 ||
|
||||||
|
status === 412 ||
|
||||||
|
(status === 422 && /does not match/i.test(message))
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Sequential PUTs, one commit per touched document (§6.1). A conflict refreshes
|
||||||
|
// that document's base and reports it without stopping the sequence; any other
|
||||||
|
// failure stops so a retry resumes from the first unwritten document — landed
|
||||||
|
// documents are never rewritten (§5.6).
|
||||||
export async function saveDraft(
|
export async function saveDraft(
|
||||||
store: DraftStore,
|
store: DraftStore,
|
||||||
onResult: (result: DocSaveResult) => void,
|
onResult: (result: DocSaveResult) => void,
|
||||||
@@ -1001,9 +1010,10 @@ export async function saveDraft(
|
|||||||
const meta = DRAFT_DOCS.find((d) => d.id === id)!;
|
const meta = DRAFT_DOCS.find((d) => d.id === id)!;
|
||||||
const paths = store.changedPaths(id);
|
const paths = store.changedPaths(id);
|
||||||
const message = `content: ${meta.file} (${paths.length} path${paths.length === 1 ? '' : 's'})`;
|
const message = `content: ${meta.file} (${paths.length} path${paths.length === 1 ? '' : 's'})`;
|
||||||
// A baseline that came from the bundle carries no blob sha. Gitea reads an
|
// A baseline that came from the bundle carries no blob sha. The API reads an
|
||||||
// empty sha as a create (422 "repository file already exists"), and PUTting
|
// empty sha as a create, and an existing file refuses it (GitHub 422 "sha must
|
||||||
// a bundle-seeded draft over the branch would drop whatever the branch has.
|
// be provided", Gitea 422 "repository file already exists"). PUTting a
|
||||||
|
// bundle-seeded draft over the branch would drop whatever the branch has.
|
||||||
// Read the branch first and hand the document to the conflict flow: rebase
|
// Read the branch first and hand the document to the conflict flow: rebase
|
||||||
// replays my paths onto the fresh base, take-theirs discards them. Reached
|
// replays my paths onto the fresh base, take-theirs discards them. Reached
|
||||||
// when a document is edited before its scoped read lands, or when a
|
// when a document is edited before its scoped read lands, or when a
|
||||||
@@ -1030,7 +1040,7 @@ export async function saveDraft(
|
|||||||
onResult(result);
|
onResult(result);
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
if (res.status === 412 || (res.status === 422 && /does not match/i.test(res.message))) {
|
if (isConflict(res.status, res.message)) {
|
||||||
try {
|
try {
|
||||||
store.resetBase(id, await fetchDoc(meta.file, branch));
|
store.resetBase(id, await fetchDoc(meta.file, branch));
|
||||||
} catch {
|
} catch {
|
||||||
|
|||||||
+10
-7
@@ -18,7 +18,7 @@ function siteIdentity(): Plugin {
|
|||||||
if (config.command === 'build' && (!siteUrl || !siteName)) {
|
if (config.command === 'build' && (!siteUrl || !siteName)) {
|
||||||
throw new Error(
|
throw new Error(
|
||||||
'SITE_URL / SITE_NAME are not set — the production build needs the site identity. ' +
|
'SITE_URL / SITE_NAME are not set — the production build needs the site identity. ' +
|
||||||
'Provide them as CI variables (Gitea Actions variables) or in the local .env; see .env.example.',
|
'Provide them as CI repository variables (GitHub Actions) or in the local .env; see .env.example.',
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
// Dev fallbacks keep `pnpm dev` bootable with no environment at all.
|
// Dev fallbacks keep `pnpm dev` bootable with no environment at all.
|
||||||
@@ -33,10 +33,11 @@ function siteIdentity(): Plugin {
|
|||||||
|
|
||||||
export default defineConfig(({ mode }) => {
|
export default defineConfig(({ mode }) => {
|
||||||
const env = loadEnv(mode, process.cwd(), '')
|
const env = loadEnv(mode, process.cwd(), '')
|
||||||
const contentsApiUrl = env.GITEA_CONTENTS_API || process.env.GITEA_CONTENTS_API || ''
|
const contentsApiUrl = env.CONTENT_API_BASE || process.env.CONTENT_API_BASE || ''
|
||||||
// Dev parity with the production nginx `/api/content/` proxy (spec-v4 §6.2):
|
// Dev parity with the production nginx `/api/content/` proxy (spec-v4 §6.2,
|
||||||
// both read the same GITEA_CONTENTS_API value. Without it there is no proxy —
|
// spec-v6 D4): both read the same CONTENT_API_BASE value and send the same
|
||||||
// edit mode falls back to the offline state, exactly like a missing token.
|
// Authorization form. Without it there is no proxy — edit mode falls back to
|
||||||
|
// the offline state, exactly like a missing token.
|
||||||
const contentsApi = contentsApiUrl ? new URL(contentsApiUrl) : null
|
const contentsApi = contentsApiUrl ? new URL(contentsApiUrl) : null
|
||||||
return {
|
return {
|
||||||
plugins: [react(), siteIdentity()],
|
plugins: [react(), siteIdentity()],
|
||||||
@@ -54,8 +55,10 @@ export default defineConfig(({ mode }) => {
|
|||||||
rewrite: (p) => p.replace(/^\/api\/content\//, contentsApi.pathname),
|
rewrite: (p) => p.replace(/^\/api\/content\//, contentsApi.pathname),
|
||||||
configure: (proxy) => {
|
configure: (proxy) => {
|
||||||
proxy.on('proxyReq', (proxyReq) => {
|
proxy.on('proxyReq', (proxyReq) => {
|
||||||
const token = env.GITEA_TOKEN || process.env.GITEA_TOKEN
|
const token = env.CONTENT_API_TOKEN || process.env.CONTENT_API_TOKEN
|
||||||
if (token) proxyReq.setHeader('Authorization', `token ${token}`)
|
// Bearer, not the legacy "token" prefix: the dev proxy must send
|
||||||
|
// exactly what the production nginx proxy sends (spec-v6 D4).
|
||||||
|
if (token) proxyReq.setHeader('Authorization', `Bearer ${token}`)
|
||||||
})
|
})
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
|
|||||||
Reference in new issue
Block a user