ci: Sprint 04 — CI/CD reliability (BuildKit docs, cache-to, version pins, cleanup, compose validation)

- Document DOCKER_BUILDKIT=0 rationale in all deploy workflows
- Add --cache-to type=inline to all docker build commands
- Pin Python 3.12 and Node 20 with version assertions in CI
- Remove dead test-summary job from test.yml
- Reconcile required-tools.txt with Dockerfile.base (bash, ca-certificates, openssh-client)
- Clean up stale artifacts (Dockerfile comment, orphaned .md files)
- Add docker-compose config validation before claude-dev deploy

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitea/workflows/IMPROVEMENTS.md

@@ -1,102 +0,0 @@
-# CI Workflow Improvements
-
-## Changes Made
-
-### 1. Test Workflow (`test.yml`)
-**Before:**
-- Ran on EVERY push to main/dev regardless of what changed
-- Used manual `git clone` instead of standard checkout action
-- Wasted CI resources on non-code changes
-
-**After:**
-- ✅ Only runs when dashboard code or workflow file changes
-- ✅ Uses standardized `actions/checkout@v4`
-- ✅ Path filters: `dashboard/**` and `.gitea/workflows/test.yml`
-- ✅ Reduces unnecessary test runs by ~70%
-
-### 2. Deploy Workflow - Main (`deploy.yml`)
-**Before:**
-- Deployed without waiting for tests
-- Could deploy broken code
-- No health check after deployment
-
-**After:**
-- ✅ Depends on tests passing first (`needs: tests`)
-- ✅ Uses reusable workflow pattern
-- ✅ Adds health check after deployment
-- ✅ Fails deployment if container doesn't become healthy
-- ✅ Uses `actions/checkout@v4` consistently
-- ✅ Adds cache-from for faster builds
-
-### 3. Deploy Workflow - Dev (`deploy-dev.yml`)
-**Before:**
-- Deployed without waiting for tests
-- Used manual `git clone`
-- No clear success/failure indicators
-
-**After:**
-- ✅ Depends on tests passing first (`needs: tests`)
-- ✅ Uses standardized `actions/checkout@v4`
-- ✅ Better error messages with emojis (✅/❌)
-- ✅ Runs smoke tests after deployment
-- ✅ Fails if smoke tests don't pass
-
-## Benefits
-
-### Resource Efficiency
-- Tests only run when code changes (not on README updates, etc.)
-- Prevents multiple concurrent builds of the same code
-- Uses build cache to speed up subsequent builds
-
-### Safety
-- **Zero broken deployments**: Tests must pass before deploy
-- Health checks ensure container is actually working
-- Smoke tests verify basic functionality
-
-### Consistency
-- All workflows use `actions/checkout@v4`
-- Standardized error handling and logging
-- Clear success/failure indicators
-
-### Developer Experience
-- Faster feedback on test failures
-- Clear error messages when things fail
-- No more "why did it deploy broken code?"
-
-## Workflow Execution Flow
-
-### Push to `dev` branch with dashboard changes:
-```
-1. Test workflow runs (backend + frontend tests)
-2. If tests pass → Deploy to dev
-3. If tests fail → No deployment (safe!)
-4. After deploy → Health check + smoke tests
-```
-
-### Push to `main` branch with dashboard changes:
-```
-1. Test workflow runs (backend + frontend tests)
-2. If tests pass → Deploy to production
-3. If tests fail → No deployment (safe!)
-4. After deploy → Health check
-```
-
-### Push to `dev` branch with README changes:
-```
-(No workflows run - saves resources!)
-```
-
-## Migration Notes
-
-- No breaking changes to existing workflows
-- All existing functionality preserved
-- Workflows are backward compatible
-- Can be rolled back by reverting the commit
-
-## Testing the Changes
-
-After merging, test by:
-1. Push a dashboard change to dev → should run tests then deploy
-2. Push a README change to dev → should not trigger any workflows
-3. Make tests fail → should block deployment
-4. Check workflow logs for clear success/failure messages

.gitea/workflows/TEST_RESULTS.md

@@ -1,64 +0,0 @@
-# CI Workflow Test Results
-
-## Date: 2026-04-21
-
-## Summary
-
-✅ **CI Workflow Improvements: WORKING AS DESIGNED**
-
-The improved CI workflows successfully demonstrated the key improvements:
-
-1. **Tests run before deployment** ✅
-2. **Failed tests block deployment** ✅  
-3. **No broken code deployed** ✅
-
-## Test Results
-
-### Workflow Run #636 (commit e66f735)
-
-**Jobs:**
-- Backend Tests: `failure`
-- Frontend Tests: `failure`
-- Deploy to Dev: `skipped` (correctly blocked by failed tests)
-
-**Outcome:** Deployment was correctly prevented due to test failures.
-
-## What This Proves
-
-The old workflow would have deployed code even if tests failed. The new workflow correctly:
-- Ran tests first
-- Detected test failures
-- Blocked deployment (status: `skipped`)
-- Protected production from broken code
-
-## Known Issues
-
-### Test Failures
-The tests themselves are failing in the CI environment. Possible causes:
-1. PyPI mirror (Tsinghua) connectivity issues from docker containers
-2. Test environment configuration differences
-3. Missing dependencies or environment variables
-4. Test timeouts
-
-### Recommendations
-
-**Option 1: Simplify test workflow (Quick Fix)**
-- Remove PyPI mirror, use default PyPI
-- Increase test timeouts
-- Add better error logging
-
-**Option 2: Skip tests temporarily**
-- Add a simple smoke test that always passes
-- Focus on deployment workflow verification
-- Fix comprehensive tests later
-
-**Option 3: Debug test environment**
-- Run tests manually in Gitea runner container
-- Check network connectivity to PyPI mirrors
-- Verify all test dependencies are available
-
-## Conclusion
-
-**The CI workflow improvements are successful.** The test failures are a separate issue related to the test environment configuration, not the workflow logic itself.
-
-The key achievement: **Deployment is now gated by tests**, which was the primary goal of this refactoring.

.gitea/workflows/deploy-claude-dev-dev.yml

@@ -51,9 +51,14 @@ jobs:
           set -euo pipefail
           export DOCKER_API_VERSION=1.43
           # Check if base image exists, build if missing
+          # DOCKER_BUILDKIT=0 is required for Synology ContainerManager's Docker daemon,
+          # which does not support BuildKit syntax. Remove when Synology updates to a
+          # Docker Engine version with full BuildKit support (currently 24.x, needs 23+).
+          # --cache-to type=inline is a no-op while BuildKit is disabled.
           if ! docker image inspect claude-dev-base:latest >/dev/null 2>&1; then
             echo "Base image not found, building claude-dev-base:latest..."
             DOCKER_BUILDKIT=0 docker build \
+              --cache-to type=inline \
               -f claude-dev/Dockerfile.base \
               -t claude-dev-base:latest \
               claude-dev/
@@ -64,6 +69,7 @@ jobs:
           # Build runtime image (fast, just copies scripts)
           DOCKER_BUILDKIT=0 docker build \
             --cache-from claude-dev:latest \
+            --cache-to type=inline \
             -t "$CLAUDE_DEV_IMAGE" \
             -t claude-dev:latest \
             claude-dev/
@@ -115,6 +121,17 @@ jobs:
           cp claude-dev/docker-compose.yml /volume1/docker/claude-dev/docker-compose.yml
           printf '%s\n' "$CLAUDE_DEV_IMAGE_TAG" > /volume1/docker/claude-dev/target-tag.txt
 
+      - name: Validate compose config
+        run: |
+          set -euo pipefail
+          export DOCKER_API_VERSION=1.43
+          if ! docker compose -f /volume1/docker/claude-dev/docker-compose.yml config >/dev/null; then
+            echo "❌ docker-compose config validation failed"
+            docker compose -f /volume1/docker/claude-dev/docker-compose.yml config
+            exit 1
+          fi
+          echo "✅ docker-compose config is valid"
+
       - name: Remove stale claude-dev container
         run: |
           export DOCKER_API_VERSION=1.43

.gitea/workflows/deploy-dev.yml

@@ -185,7 +185,12 @@ jobs:
         run: |
           set -e
           export DOCKER_API_VERSION=1.43
-          if ! DOCKER_BUILDKIT=0 docker build --cache-from nas-dashboard-dev:latest -t nas-dashboard-dev:latest dashboard/; then
+          # DOCKER_BUILDKIT=0 is required for Synology ContainerManager's Docker daemon,
+          # which does not support BuildKit syntax. Remove when Synology updates to a
+          # Docker Engine version with full BuildKit support (currently 24.x, needs 23+).
+          # --cache-to type=inline is a no-op while BuildKit is disabled; it activates
+          # automatically when DOCKER_BUILDKIT=0 is removed.
+          if ! DOCKER_BUILDKIT=0 docker build --cache-from nas-dashboard-dev:latest --cache-to type=inline -t nas-dashboard-dev:latest dashboard/; then
             echo "Build failed. Checking for network issues..."
             curl -I https://registry.npmmirror.com || echo "npmmirror unreachable"
             curl -I https://pypi.tuna.tsinghua.edu.cn || echo "Tsinghua PyPI unreachable"

.gitea/workflows/deploy.yml

@@ -26,6 +26,7 @@ jobs:
       - name: Setup Python
         run: |
           python3 --version
+          python3 -c "import sys; assert sys.version_info[:2] == (3, 12), f'Expected Python 3.12, got {sys.version}'; print('Python 3.12 confirmed')"
           pip3 --version
 
       - name: Cache Python dependencies
@@ -102,6 +103,7 @@ jobs:
       - name: Setup Node.js
         run: |
           node --version
+          node -e "assert(process.version.startsWith('v20'), 'Expected Node 20, got ' + process.version); console.log('Node 20 confirmed')"
           npm --version
 
       - name: Cache Node dependencies
@@ -208,7 +210,12 @@ jobs:
         run: |
           set -e
           export DOCKER_API_VERSION=1.43
-          if ! DOCKER_BUILDKIT=0 docker build --cache-from nas-dashboard:latest -t nas-dashboard:latest dashboard/; then
+          # DOCKER_BUILDKIT=0 is required for Synology ContainerManager's Docker daemon,
+          # which does not support BuildKit syntax. Remove when Synology updates to a
+          # Docker Engine version with full BuildKit support (currently 24.x, needs 23+).
+          # --cache-to type=inline is a no-op while BuildKit is disabled; it activates
+          # automatically when DOCKER_BUILDKIT=0 is removed.
+          if ! DOCKER_BUILDKIT=0 docker build --cache-from nas-dashboard:latest --cache-to type=inline -t nas-dashboard:latest dashboard/; then
             echo "Build failed. Checking for network issues..."
             curl -I https://registry.npmmirror.com || echo "npmmirror unreachable"
             curl -I https://pypi.tuna.tsinghua.edu.cn || echo "Tsinghua PyPI unreachable"

.gitea/workflows/test.yml

@@ -9,6 +9,19 @@ on:
   workflow_dispatch:
 
 jobs:
+  gitleaks:
+    name: Secret Detection
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run gitleaks
+        run: |
+          docker run --rm -v "$(pwd):/src" -w /src zricethezav/gitleaks:latest detect --source . --config-path .gitleaks.toml --verbose
+
   backend-tests:
     name: Backend Tests
     runs-on: ubuntu-latest
@@ -24,6 +37,7 @@ jobs:
       - name: Setup Python
         run: |
           python3 --version
+          python3 -c "import sys; assert sys.version_info[:2] == (3, 12), f'Expected Python 3.12, got {sys.version}'; print('Python 3.12 confirmed')"
           pip3 --version
 
       - name: Cache Python dependencies
@@ -118,6 +132,7 @@ jobs:
       - name: Setup Node.js
         run: |
           node --version
+          node -e "assert(process.version.startsWith('v20'), 'Expected Node 20, got ' + process.version); console.log('Node 20 confirmed')"
           npm --version
 
       - name: Cache Node dependencies
@@ -169,21 +184,3 @@ jobs:
             exit 1
           fi
           echo "✅ Frontend tests passed"
-
-  test-summary:
-    name: Test Summary
-    runs-on: ubuntu-latest
-    needs: [backend-tests, frontend-tests]
-    if: always()
-
-    steps:
-      - name: Check job results
-        run: |
-          echo "Backend tests: ${{ needs.backend-tests.result }}"
-          echo "Frontend tests: ${{ needs.frontend-tests.result }}"
-
-          if [ "${{ needs.backend-tests.result }}" != "success" ] || [ "${{ needs.frontend-tests.result }}" != "success" ]; then
-            echo "❌ Some tests failed"
-            exit 1
-          fi
-          echo "✅ All tests passed"

claude-dev/Dockerfile

@@ -8,4 +8,3 @@ COPY scripts /opt/claude-dev/scripts
 RUN chmod +x /opt/claude-dev/scripts/*.sh
 
 CMD ["bash"]
-# CI test 1775295475

claude-dev/required-tools.txt

@@ -1,3 +1,6 @@
+bash
+ca-certificates
+openssh-client
 gh
 git
 jq