15 KiB
15 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | user_setup | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 06-desktop-client-ci-cd | 03 | execute | 1 |
|
false |
|
|
|
Purpose: Minimal-manual-effort version control + CI/CD so milestone pushes automatically lint, test, build, and redeploy the running stack.
Output: .gitea/workflows/ci.yml, an act_runner service definition, and a setup runbook.
<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/06-desktop-client-ci-cd/06-CONTEXT.md @.planning/phases/06-desktop-client-ci-cd/06-RESEARCH.md @docker-compose.yml @package.json @turbo.json<artifacts_this_phase_produces>
.gitea/workflows/ci.yml— CI/CD pipeline (quality / test / build-deploy jobs)docker-compose.ci.yml— act_runner service (Docker socket mount, ephemeral mode)docs/ci-cd-setup.md— runbook for Gitea remote + runner registration + secrets </artifacts_this_phase_produces>
The executor presents these steps; the human performs them and supplies values back:
1. Confirm the Gitea base URL (e.g. https://gitea.example). If Gitea is not running, decide whether to add it
to docker-compose or use an existing instance.
2. Create a repository (e.g. `tessera`) and run `git remote add origin <gitea-repo-url>`.
3. In Gitea, enable Actions for the repo (Settings → Actions) and generate an act_runner registration token
(Admin/Repo → Actions → Runners → Create registration token).
4. Provide the runner registration token + Gitea instance URL so Task 2 can configure the runner, and confirm
the deploy host has the project checked out at the docker-compose path for `docker compose` deploys.
Create `docs/ci-cd-setup.md` runbook documenting: (1) the Gitea repo + remote setup from Task 1, (2) how to
start the runner `docker compose -f docker-compose.ci.yml up -d`, (3) required secrets/vars
(GITEA_INSTANCE_URL, GITEA_RUNNER_REGISTRATION_TOKEN, and any deploy secrets used by ci.yml such as the deploy
path), (4) the Docker socket security note + ephemeral runner rationale (Pitfall 5), (5) that registry push is
intentionally skipped — images build locally on the same server (D-13, RESEARCH anti-pattern).
1. `quality` (runs-on ubuntu-latest): `actions/checkout@v4`, `pnpm/action-setup@v4` (version 9, matching
packageManager pnpm@9.15.0), `actions/setup-node@v4` (node-version 24, cache pnpm), `pnpm install
--frozen-lockfile`, `pnpm lint` (Biome via turbo), `pnpm type-check`.
2. `test` (needs: quality): same checkout/pnpm/node setup, `pnpm install --frozen-lockfile`, `pnpm test`
(Vitest via turbo — `apps/web/vitest.config.ts` exists).
3. `build-deploy` (needs: test): checkout, then build + deploy with PLAIN docker compose commands (Pitfall 4 —
do NOT use docker/build-push-action which fails on Gitea's non-JWT token; Pattern 4 + RESEARCH anti-pattern):
`docker compose build web api` then `docker compose up -d web api`. Since the deploy target is the same
server as the runner (D-13), this builds images locally and restarts the services with no registry push.
Never echo secrets in steps. If the runbook (Task 2) defines deploy secrets/vars (e.g. a deploy path), read
them via Gitea Actions `${{ secrets.* }}` / `${{ vars.* }}`, not inline literals (Security Domain: CI secrets
leakage). Keep the workflow minimal and readable per CLAUDE.md (Claude builds maintainable infra).
Before this checkpoint the executor ensures the runner is up (`docker compose -f docker-compose.ci.yml up -d`)
and the workflow + compose files are committed to the branch that will be pushed.
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| Gitea push → act_runner execution | Pushed workflow code executes on the runner with Docker socket access |
| act_runner → host Docker daemon | Mounted /var/run/docker.sock grants the runner control over host containers |
| pipeline → secrets store | Deploy/registration secrets pass through Gitea Actions context |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-06-07 | Elevation | act_runner Docker socket mount | accept | Internal-only CI, only Claude pushes (D-11); GITEA_RUNNER_EPHEMERAL=1 revokes creds per job (Pitfall 5) |
| T-06-08 | Information Disclosure | secrets in pipeline logs | mitigate | Reference secrets via ${{ secrets.* }}/${{ vars.* }}; never echo; registration token from env not hardcoded (Security Domain) |
| T-06-09 | Tampering | malicious workflow modification | accept | Single trusted committer (Claude), push to main only; no external contributors (D-10/D-11) |
| T-06-SC | Tampering | act_runner image | mitigate | Use official gitea/act_runner image; CI actions pinned to major (checkout@v4, setup-node@v4) |
| </threat_model> |
<success_criteria>
- Gitea remote configured and main pushed (INFRA-04)
- act_runner registered and executing jobs
- Multi-stage pipeline (lint+type-check → tests → docker build+deploy) runs on push (D-12, D-13)
- No Git/Gitea functionality added to the Tessera app itself (D-10) </success_criteria>