From 21d81ec74c251bfa5815cef7feb1a55d2474f051 Mon Sep 17 00:00:00 2001 From: copilotcoder Date: Wed, 1 Jul 2026 17:37:08 -0400 Subject: [PATCH] ci: add source-first fast-check gate before build promotion --- .gitea/workflows/cicd-source-checks.yaml | 392 +++++++++++++++++++++++ .gitea/workflows/cicd-start.yaml | 6 +- docs/CICD_MULTI_STAGE_BUILD.md | 7 +- docs/DEVELOPMENT.md | 38 +-- 4 files changed, 414 insertions(+), 29 deletions(-) create mode 100644 .gitea/workflows/cicd-source-checks.yaml diff --git a/.gitea/workflows/cicd-source-checks.yaml b/.gitea/workflows/cicd-source-checks.yaml new file mode 100644 index 0000000..e3d55e1 --- /dev/null +++ b/.gitea/workflows/cicd-source-checks.yaml @@ -0,0 +1,392 @@ +name: CICD Source Checks + +on: + workflow_dispatch: + inputs: + head_sha: + description: Commit SHA to process + required: false + source_workflow: + description: Upstream workflow name + required: false + trace_id: + description: Correlation id propagated across CICD dispatch chain + required: false + base_needed: + description: Whether base rebuild is required downstream + required: false + base_hash: + description: Immutable base hash to pass downstream + required: false + +env: + GITEA_SSH_HOST: kankali.darkhelm.lan + GITEA_SSH_PORT: "2222" + GITEA_REPO_SSH_URL: ssh://git@kankali.darkhelm.lan:2222/DarkHelm.org/plex-playlist.git + GITEA_REGISTRY: kankali.darkhelm.lan:3001 + GITEA_REGISTRY_IP: 10.18.75.2 + GITEA_REGISTRY_HOST: kankali.darkhelm.lan + +concurrency: + group: source-checks-${{ github.sha }} + cancel-in-progress: true + +jobs: + setup: + name: Setup Source Checks Context + runs-on: ubuntu-act + timeout-minutes: 10 + outputs: + head_sha: ${{ steps.meta.outputs.head_sha }} + trace_id: ${{ steps.meta.outputs.trace_id }} + base_needed: ${{ steps.meta.outputs.base_needed }} + base_hash: ${{ steps.meta.outputs.base_hash }} + steps: + - name: Identify runner + run: | + echo "=== Runner Identity ===" + echo "runner_name=${RUNNER_NAME:-}" + echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}" + echo "runner_hostname_env=${HOSTNAME:-unknown}" + echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)" + echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)" + echo "runner_os=${RUNNER_OS:-unknown}" + echo "runner_arch=${RUNNER_ARCH:-unknown}" + echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)" + + - name: Audit trigger context + env: + EVENT_NAME: ${{ github.event_name }} + SOURCE_WORKFLOW: ${{ github.event.inputs.source_workflow }} + HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }} + HEAD_SHA_FALLBACK: ${{ github.sha }} + BASE_NEEDED_INPUT: ${{ github.event.inputs.base_needed }} + BASE_HASH_INPUT: ${{ github.event.inputs.base_hash }} + REF: ${{ github.ref }} + REF_NAME: ${{ github.ref_name }} + HEAD_REF: ${{ github.head_ref }} + TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }} + run: | + RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}" + RESOLVED_BASE_NEEDED="${BASE_NEEDED_INPUT:-true}" + TRACE_ID="${TRACE_ID_INPUT:-cicd-source-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}" + echo "=== Dispatch Audit: CICD Source Checks ===" + echo "event_name=${EVENT_NAME}" + echo "source_workflow=${SOURCE_WORKFLOW}" + echo "head_sha_input=${HEAD_SHA_INPUT}" + echo "head_sha=${RESOLVED_HEAD_SHA}" + echo "base_needed=${RESOLVED_BASE_NEEDED}" + echo "base_hash=${BASE_HASH_INPUT:-deferred}" + echo "ref=${REF}" + echo "ref_name=${REF_NAME}" + echo "head_ref=${HEAD_REF}" + echo "trace_id=${TRACE_ID}" + + - name: Resolve source check metadata + id: meta + env: + HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }} + HEAD_SHA_FALLBACK: ${{ github.sha }} + TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }} + BASE_NEEDED_INPUT: ${{ github.event.inputs.base_needed }} + BASE_HASH_INPUT: ${{ github.event.inputs.base_hash }} + run: | + RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}" + RESOLVED_TRACE_ID="${TRACE_ID_INPUT:-cicd-source-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}" + RESOLVED_BASE_NEEDED="${BASE_NEEDED_INPUT:-true}" + RESOLVED_BASE_HASH="${BASE_HASH_INPUT:-deferred}" + + echo "head_sha=${RESOLVED_HEAD_SHA}" >> "$GITHUB_OUTPUT" + echo "trace_id=${RESOLVED_TRACE_ID}" >> "$GITHUB_OUTPUT" + echo "base_needed=${RESOLVED_BASE_NEEDED}" >> "$GITHUB_OUTPUT" + echo "base_hash=${RESOLVED_BASE_HASH}" >> "$GITHUB_OUTPUT" + + - &failure_diagnostics_step + name: Failure diagnostics + if: failure() + run: | + echo "=== Failure Diagnostics ===" + date -u '+timestamp_utc=%Y-%m-%dT%H:%M:%SZ' + echo "runner_name=${RUNNER_NAME:-unknown}" + echo "runner_hostname=${HOSTNAME:-unknown}" + uname -a || true + cat /etc/os-release 2>/dev/null || true + df -h || true + free -h || true + ps aux --sort=-%mem | head -n 30 || true + + if command -v docker >/dev/null 2>&1; then + echo "=== Docker Diagnostics ===" + docker version || true + docker info || true + docker ps -a || true + docker images --digests | head -n 50 || true + else + echo "docker not available on this runner" + fi + + echo "=== Kernel Tail ===" + dmesg | tail -n 120 || true + + backend-source-checks: + name: Backend Source Checks (format/lint/type) + runs-on: ubuntu-act + timeout-minutes: 25 + needs: setup + steps: + - name: Identify runner + run: | + echo "=== Runner Identity ===" + echo "runner_name=${RUNNER_NAME:-}" + echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}" + echo "runner_hostname_env=${HOSTNAME:-unknown}" + echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)" + echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)" + echo "runner_os=${RUNNER_OS:-unknown}" + echo "runner_arch=${RUNNER_ARCH:-unknown}" + echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)" + + - name: Configure registry host resolution + run: | + if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then + echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts + fi + + - name: Checkout source snapshot + env: + SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} + HEAD_SHA: ${{ needs.setup.outputs.head_sha }} + run: | + set -e + umask 077 + trap 'rm -f ~/.ssh/id_rsa' EXIT + + mkdir -p ~/.ssh + echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa + chmod 600 ~/.ssh/id_rsa + ssh-keyscan -p "${GITEA_SSH_PORT}" "${GITEA_SSH_HOST}" >> ~/.ssh/known_hosts 2>/dev/null + + GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \ + git clone --depth 1 --no-checkout "${GITEA_REPO_SSH_URL}" . + + if GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \ + git fetch --depth 1 origin "${HEAD_SHA}" >/dev/null 2>&1; then + git checkout FETCH_HEAD -- backend + echo "Using fetched HEAD_SHA checkout: ${HEAD_SHA}" + else + git checkout HEAD -- backend + echo "Falling back to default branch HEAD for backend source checkout" + fi + + - name: Run backend format/lint/type checks + run: | + set -e + docker run --rm -v "$PWD:/workspace" -w /workspace/backend python:3.14-slim bash -lc ' + set -e + python -m pip install --disable-pip-version-check --no-cache-dir uv + uv sync --dev + uv run ruff format --check . + uv run ruff check . + uv run pyright . + ' + + - *failure_diagnostics_step + + frontend-source-checks: + name: Frontend Source Checks (format/lint/type) + runs-on: ubuntu-act + timeout-minutes: 25 + needs: setup + steps: + - name: Identify runner + run: | + echo "=== Runner Identity ===" + echo "runner_name=${RUNNER_NAME:-}" + echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}" + echo "runner_hostname_env=${HOSTNAME:-unknown}" + echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)" + echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)" + echo "runner_os=${RUNNER_OS:-unknown}" + echo "runner_arch=${RUNNER_ARCH:-unknown}" + echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)" + + - name: Configure registry host resolution + run: | + if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then + echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts + fi + + - name: Checkout source snapshot + env: + SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} + HEAD_SHA: ${{ needs.setup.outputs.head_sha }} + run: | + set -e + umask 077 + trap 'rm -f ~/.ssh/id_rsa' EXIT + + mkdir -p ~/.ssh + echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa + chmod 600 ~/.ssh/id_rsa + ssh-keyscan -p "${GITEA_SSH_PORT}" "${GITEA_SSH_HOST}" >> ~/.ssh/known_hosts 2>/dev/null + + GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \ + git clone --depth 1 --no-checkout "${GITEA_REPO_SSH_URL}" . + + if GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \ + git fetch --depth 1 origin "${HEAD_SHA}" >/dev/null 2>&1; then + git checkout FETCH_HEAD -- frontend + echo "Using fetched HEAD_SHA checkout: ${HEAD_SHA}" + else + git checkout HEAD -- frontend + echo "Falling back to default branch HEAD for frontend source checkout" + fi + + - name: Run frontend format/lint/type checks + run: | + set -e + docker run --rm -v "$PWD:/workspace" -w /workspace/frontend node:24-bullseye bash -lc ' + set -e + corepack enable + yarn install --immutable || yarn install + yarn prettier --check src/ + yarn lint + yarn type-check + ' + + - *failure_diagnostics_step + + dispatch-build: + name: Dispatch Downstream Build + runs-on: ubuntu-act + timeout-minutes: 10 + needs: [setup, backend-source-checks, frontend-source-checks] + steps: + - name: Identify runner + run: | + echo "=== Runner Identity ===" + echo "runner_name=${RUNNER_NAME:-}" + echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}" + echo "runner_hostname_env=${HOSTNAME:-unknown}" + echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)" + echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)" + echo "runner_os=${RUNNER_OS:-unknown}" + echo "runner_arch=${RUNNER_ARCH:-unknown}" + echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)" + + - name: Configure registry host resolution + run: | + if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then + echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts + fi + + - name: Dispatch downstream workflow + env: + ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }} + PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }} + BASE_NEEDED: ${{ needs.setup.outputs.base_needed }} + BASE_HASH: ${{ needs.setup.outputs.base_hash }} + HEAD_SHA: ${{ needs.setup.outputs.head_sha }} + TRACE_ID: ${{ needs.setup.outputs.trace_id }} + REPO_FULL: ${{ github.repository }} + HEAD_REF: ${{ github.head_ref }} + REF_NAME: ${{ github.ref_name }} + run: | + set -e + + DISPATCH_TOKEN="${ACTIONS_TRIGGER_TOKEN:-${PACKAGE_ACCESS_TOKEN:-}}" + + if [ -z "${DISPATCH_TOKEN}" ]; then + echo "❌ Missing dispatch token. Set ACTIONS_TRIGGER_TOKEN (repo write scope) or ensure PACKAGE_ACCESS_TOKEN has Actions workflow-dispatch permissions." + exit 1 + fi + + REPO_OWNER="${REPO_FULL%/*}" + REPO_NAME="${REPO_FULL#*/}" + TARGET_REF="${HEAD_REF:-${REF_NAME}}" + + if [ "${BASE_NEEDED}" = "true" ]; then + TARGET_WORKFLOW="docker-build-base.yaml" + else + TARGET_WORKFLOW="docker-build-main.yaml" + fi + + CANDIDATE_API_BASES=() + if [ -n "${GITHUB_SERVER_URL:-}" ]; then + CANDIDATE_API_BASES+=("${GITHUB_SERVER_URL%/}/api/v1") + fi + if [ -n "${GITEA_SSH_HOST:-}" ]; then + CANDIDATE_API_BASES+=("http://${GITEA_SSH_HOST}:3001/api/v1") + fi + if [ -n "${GITEA_REGISTRY_HOST:-}" ]; then + CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_HOST}:3001/api/v1") + fi + if [ -n "${GITEA_REGISTRY_IP:-}" ]; then + CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_IP}:3001/api/v1") + fi + + ensure_curl() { + if command -v curl >/dev/null 2>&1; then + return 0 + fi + + if command -v apt-get >/dev/null 2>&1; then + export DEBIAN_FRONTEND=noninteractive + apt-get update -qq + apt-get install -y -qq curl ca-certificates + fi + + if command -v curl >/dev/null 2>&1; then + return 0 + fi + + echo "❌ curl is required for dispatch and could not be installed" + return 1 + } + + ensure_curl + + HELPER_PATH="/tmp/dispatch-workflow.sh" + + fetch_dispatch_helper() { + local helper_ref="$1" + local api_base + for api_base in "${CANDIDATE_API_BASES[@]}"; do + helper_url="${api_base}/repos/${REPO_OWNER}/${REPO_NAME}/raw/scripts/dispatch-workflow.sh?ref=${helper_ref}" + if curl -fsS --connect-timeout 5 --max-time 20 \ + -H "Authorization: token ${DISPATCH_TOKEN}" \ + -H "User-Agent: plex-playlist-cicd-source-checks" \ + -o "${HELPER_PATH}" \ + "${helper_url}"; then + chmod +x "${HELPER_PATH}" + return 0 + fi + done + return 1 + } + + if ! fetch_dispatch_helper "${TARGET_REF}" && ! fetch_dispatch_helper "${HEAD_SHA}"; then + echo "❌ Failed to fetch scripts/dispatch-workflow.sh from repository" + exit 1 + fi + + DISPATCH_ARGS=( + --token "${DISPATCH_TOKEN}" + --repo "${REPO_FULL}" + --workflow "${TARGET_WORKFLOW}" + --ref "${TARGET_REF}" + --head-sha "${HEAD_SHA}" + --source-workflow "CICD Source Checks" + --trace-id "${TRACE_ID}" + --base-needed "${BASE_NEEDED}" + --base-hash "${BASE_HASH}" + ) + + for API_BASE in "${CANDIDATE_API_BASES[@]}"; do + DISPATCH_ARGS+=(--api-base "${API_BASE}") + done + + echo "✅ Source checks passed; dispatching ${TARGET_WORKFLOW}" + "${HELPER_PATH}" "${DISPATCH_ARGS[@]}" + + - *failure_diagnostics_step diff --git a/.gitea/workflows/cicd-start.yaml b/.gitea/workflows/cicd-start.yaml index aa50227..c1190b3 100644 --- a/.gitea/workflows/cicd-start.yaml +++ b/.gitea/workflows/cicd-start.yaml @@ -120,11 +120,7 @@ jobs: echo "trace_id=${TRACE_ID}" echo "target_ref=${TARGET_REF}" - if [ "${BASE_NEEDED}" = "true" ]; then - TARGET_WORKFLOW="docker-build-base.yaml" - else - TARGET_WORKFLOW="docker-build-main.yaml" - fi + TARGET_WORKFLOW="cicd-source-checks.yaml" CANDIDATE_API_BASES=() if [ -n "${GITHUB_SERVER_URL:-}" ]; then diff --git a/docs/CICD_MULTI_STAGE_BUILD.md b/docs/CICD_MULTI_STAGE_BUILD.md index b370e51..9f1691d 100644 --- a/docs/CICD_MULTI_STAGE_BUILD.md +++ b/docs/CICD_MULTI_STAGE_BUILD.md @@ -142,10 +142,13 @@ jobs: ### Responsibility Split +- `.gitea/workflows/cicd-start.yaml` owns startup routing and trace propagation. +- `.gitea/workflows/cicd-source-checks.yaml` owns early source-level + format/lint/type gating before any promotion dispatch. - `.gitea/workflows/docker-build-base.yaml` owns base publication and verification. - `.gitea/workflows/docker-build-main.yaml` owns complete-image publication. -- `.gitea/workflows/cicd-start.yaml`, `.gitea/workflows/cicd-checks.yaml`, and - `.gitea/workflows/cicd-tests.yaml` own CI validation and checks. +- `.gitea/workflows/cicd-checks.yaml` and `.gitea/workflows/cicd-tests.yaml` + own post-build CI validation and tests. - Main CI never rebuilds the base image locally. ### Runtime Boundary Enforcement diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 85a7dd1..d528284 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -390,8 +390,9 @@ pre-commit run end-of-file-fixer --all-files The CI/CD pipeline uses a **multi-stage build architecture** for optimal performance: -- **Stage 1**: Build base image (system dependencies, Python, Node.js) - **cached across runs** -- **Stage 2**: Build complete image (project code and dependencies) - **rebuilt every time** +- **Stage 1**: Source-level fast checks (format, lint, type-check) - **hard promotion gate** +- **Stage 2**: Build base image (system dependencies, Python, Node.js) - **cached across runs** +- **Stage 3**: Build complete image (project code and dependencies) - **rebuilt every time** Pipeline triggers: @@ -425,26 +426,19 @@ For detailed technical information, see [CI/CD Multi-Stage Build Architecture](C All jobs run in parallel after the setup phases: -1. **Setup Base**: Builds and pushes base Docker image (conditional) -2. **Setup Complete**: Builds and pushes complete CI/CD Docker image -3. **Code Quality**: - - Trailing whitespace check - - End-of-file formatting - - YAML syntax validation - - TOML syntax validation -4. **Backend Validation**: - - Ruff formatting check - - Ruff linting - - Pyright type checking - - Darglint docstring validation - - Unit tests with coverage - - Integration tests - - Doctests (xdoctest) -5. **Frontend Validation**: - - Prettier formatting check - - ESLint linting - - TypeScript compilation - - Unit tests with coverage +1. **Source Fast Gate**: + Backend source checks (Ruff format/lint, Pyright), frontend source checks (Prettier, ESLint, TypeScript), and dispatches downstream build only on success. + +2. **Setup Base**: Builds and pushes base Docker image (conditional) +3. **Setup Complete**: Builds and pushes complete CI/CD Docker image +4. **Code Quality**: + Trailing whitespace check, end-of-file formatting, YAML syntax validation, and TOML syntax validation. + +5. **Backend Validation**: + Ruff formatting check, Ruff linting, Pyright type checking, Darglint docstring validation, unit tests with coverage, integration tests, and doctests (xdoctest). + +6. **Frontend Validation**: + Prettier formatting check, ESLint linting, TypeScript compilation, and unit tests with coverage. - E2E tests (Playwright) ### Local CI/CD Testing