nas-tools/specs/sprint-04-ci-cd-reliability.md

Sprint 04 — CI/CD Reliability

Depends on: S01 (production must be stable before iterating on CI) Duration: ~10h Goal: Document BuildKit rationale, add cache persistence, pin tool versions, remove dead code, reconcile tool lists, clean up artifacts, add compose validation.

---

S04.1 — Document DOCKER_BUILDKIT=0 rationale

• Files: .gitea/workflows/deploy.yml, deploy-dev.yml, deploy-claude-dev-dev.yml

• Estimate: 0.5h

• Done means: Each workflow has a comment explaining DOCKER_BUILDKIT=0 (Synology ContainerManager Docker daemon compatibility).

• Verify by: Read the workflow files → comments present.

• Risk: None — comment-only change.

• S04.1 — Document DOCKER_BUILDKIT=0 rationale

S04.2 — Add --cache-to inline to Docker builds

• Files: .gitea/workflows/deploy.yml, deploy-dev.yml, deploy-claude-dev-dev.yml

• Estimate: 1h

• Done means: All docker build commands have --cache-to type=inline alongside existing --cache-from. Build cache layers are embedded in the image manifest.

• Verify by:

  1. Push to dev → first build takes normal time
  2. Push again without code changes → second build uses cache, significantly faster
  3. Check build logs for "CACHED" markers

• Risk: --cache-to type=inline only works with DOCKER_BUILDKIT=1. Since BuildKit is disabled (S04.1), this is currently a no-op. Document that it activates when BuildKit is re-enabled.

• S04.2 — Add --cache-to inline to Docker builds

S04.3 — Pin Node.js and Python versions in CI

• Files: .gitea/workflows/test.yml, deploy.yml

• Estimate: 1.5h

• Done means: CI uses explicit Python 3.12 and Node.js 20. Matches versions in Dockerfiles (python:3.12-slim, node:20-alpine).

• Verify by: CI run logs show Python 3.12.x and Node v20.x.x.

• Risk: If Gitea runner lacks actions/setup-python/actions/setup-node, pin via container: directive (e.g., container: python:3.12-slim).

• S04.3 — Pin Node.js and Python versions in CI

S04.4 — Remove dead test-summary job

• Files: .gitea/workflows/deploy.yml:173-189

• Estimate: 0.5h

• Done means: test-summary job removed from deploy.yml. Deploy still depends on backend-tests and frontend-tests directly.

• Verify by:

  1. Push to main → tests pass → deploy proceeds
  2. Push with failing test → deploy skipped

• Risk: None — dead code removal.

• S04.4 — Remove dead test-summary job

S04.5 — Reconcile required-tools.txt with Dockerfile.base

• Files: claude-dev/required-tools.txt, claude-dev/Dockerfile.base

• Estimate: 1h

• Done means: bash, ca-certificates, and openssh-client added to required-tools.txt (all needed at runtime). smoke-tools.sh passes.

• Verify by:

  1. smoke-tools.sh passes on updated container
  2. Container functions correctly (SSH works, HTTPS requests work, scripts run)

• Risk: These are runtime dependencies — adding to the list is the right call.

• S04.5 — Reconcile required-tools.txt with Dockerfile.base

S04.6 — Clean up stale artifacts

• Files: claude-dev/Dockerfile:11, .gitea/workflows/TEST_RESULTS.md, .gitea/workflows/IMPROVEMENTS.md

• Estimate: 0.5h

• Done means: Stale comment removed. Orphaned .md files moved to docs/ or deleted.

• Verify by: grep "CI test 1775295475" claude-dev/Dockerfile → no match. .gitea/workflows/ contains only YAML files.

• Risk: None.

• S04.6 — Clean up stale artifacts

S04.7 — Add docker-compose config validation to CI

• Files: .gitea/workflows/deploy-claude-dev-dev.yml:112-116

• Estimate: 1h

• Done means: Before docker compose up, CI validates compose file with docker compose config. Invalid files block deploy.

• Verify by:

  1. Normal deploy → config validation passes → deploy proceeds
  2. Corrupted compose file → config validation fails → deploy blocked

• Risk: docker compose config requires Docker daemon running. Networks referenced but not existing produce warnings, not errors — acceptable.

• S04.7 — Add docker-compose config validation to CI

---

Exit criteria

• All workflows have comments explaining DOCKER_BUILDKIT=0
• All docker build commands include --cache-to type=inline
• CI logs show pinned Python 3.12 and Node 20 versions
• deploy.yml has no test-summary job
• required-tools.txt includes bash, ca-certificates, openssh-client
• No stale debug comment in claude-dev/Dockerfile
• .gitea/workflows/ contains only YAML files
• Deploy includes compose config validation step
• CI workflows pass on push to dev