TASK: Replace integration lane with post-build backend runtime black-box tests (#72)

## Summary

Replace the existing source-context integration lane with backend runtime black-box integration checks that run against started deployable containers.

This change wires deployable backend image references (both commit tag and immutable digest) from the build workflow into the tests workflow, then validates runtime behavior over network endpoints.

## Why

Integration confidence should come from testing running service artifacts, not only source-mounted or in-process execution.

## What Changed

- Build workflow now:
  - Publishes deployable backend image tag reference and digest reference
  - Exposes both as job outputs
  - Passes both references into CICD Tests dispatch inputs

- CICD Tests workflow now:
  - Accepts deployable backend tag and digest inputs
  - Propagates these through setup outputs
  - Replaces previous integration lane behavior with runtime black-box execution:
    - Starts isolated Docker network
    - Starts Postgres container
    - Starts backend container from digest-pinned deployable image
    - Enforces tag-to-digest consistency before running checks
    - Runs endpoint checks against live container:
      - GET /
      - GET /compatibility
      - GET /health
    - Captures backend/db logs and container state on failure
    - Cleans up containers and network via trap

- Documentation updated:
  - Runtime contract enforcement section now includes runtime black-box integration checks
  - CI success summary now reflects runtime integration lane behavior

## Scope

Included:
- Backend runtime black-box integration replacement for the existing integration lane
- Digest + tag identity enforcement
- Failure diagnostics for triage

Out of scope:
- Frontend runtime smoke checks
- E2E lane redesign

## Acceptance Criteria Mapping

- Integration tests execute against runtime container endpoints: ✅
- Integration lane consumes built image references (not source-mounted execution): ✅
- Failures surface service logs and test logs for triage: ✅

## Verification

- Workflow files pass local validation checks
- Pre-commit hooks pass on committed changes
- Branch pushed and ready for PR review

## Related

- Issue: #61
- Dependency context: #66

Co-authored-by: copilotcoder <copilotcoder@darkhelm.org>
Reviewed-on: #72

.gitea/workflows/cicd-source-checks.yaml

@@ -128,8 +128,8 @@ jobs:
           echo "=== Kernel Tail ==="
           dmesg | tail -n 120 || true
 
-  source-precommit-checks:
-    name: Source Pre-commit Checks (backend+frontend)
+  source-precommit-checks-backend:
+    name: Source Pre-commit Checks (backend)
     runs-on: ubuntu-act
     timeout-minutes: 40
     needs: setup
@@ -194,7 +194,104 @@ jobs:
             exit 1
           }
 
-      - name: Bootstrap source-check toolchain
+      - name: Bootstrap backend toolchain
+        run: |
+          set -euo pipefail
+
+          if ! command -v curl >/dev/null 2>&1; then
+            apt-get update -qq
+            apt-get install -y -qq curl ca-certificates
+          fi
+
+          if ! command -v uv >/dev/null 2>&1; then
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+          fi
+          export PATH="$HOME/.local/bin:$PATH"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Install backend dependencies
+        run: |
+          set -euo pipefail
+          export PATH="$HOME/.local/bin:$PATH"
+          export UV_LINK_MODE=copy
+
+          cd backend
+          uv sync --dev
+
+      - name: Run backend pre-commit source checks
+        env:
+          CI: "true"
+          SKIP: "eslint,prettier,typescript-check,tsdoc-lint"
+        run: |
+          set -euo pipefail
+          export PATH="$HOME/.local/bin:$PATH"
+          cd backend
+          uv run pre-commit run --all-files --show-diff-on-failure --config ../.pre-commit-config.yaml
+
+      - *failure_diagnostics_step
+
+  source-precommit-checks-frontend:
+    name: Source Pre-commit Checks (frontend)
+    runs-on: ubuntu-act
+    timeout-minutes: 40
+    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 022
+          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 -- .
+            echo "Using fetched HEAD_SHA checkout: ${HEAD_SHA}"
+          else
+            git checkout HEAD -- .
+            echo "Falling back to default branch HEAD for source checks checkout"
+          fi
+
+          test -f .pre-commit-config.yaml || {
+            echo "❌ Missing .pre-commit-config.yaml after checkout"
+            exit 1
+          }
+
+          test -f frontend/package.json || {
+            echo "❌ Missing frontend/package.json after checkout"
+            find . -maxdepth 3 -type f | sort | head -n 80
+            exit 1
+          }
+
+      - name: Bootstrap frontend toolchain
         run: |
           set -euo pipefail
 
@@ -203,14 +300,12 @@ jobs:
             apt-get install -y -qq curl ca-certificates
           fi
 
-          # Install uv if missing and expose it for subsequent steps.
           if ! command -v uv >/dev/null 2>&1; then
             curl -LsSf https://astral.sh/uv/install.sh | sh
           fi
           export PATH="$HOME/.local/bin:$PATH"
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-          # Ensure node/corepack is available for frontend and pre-commit hooks.
           if ! command -v node >/dev/null 2>&1; then
             apt-get update -qq
             apt-get install -y -qq nodejs npm
@@ -221,24 +316,27 @@ jobs:
 
           corepack enable
 
-      - name: Install backend and frontend dependencies
+      - name: Install frontend dependencies
         run: |
           set -euo pipefail
-          export PATH="$HOME/.local/bin:$PATH"
+          export NODE_OPTIONS="--max-old-space-size=512"
+          export YARN_NETWORK_CONCURRENCY=1
+          cd frontend
+          if ! yarn install --immutable --mode=skip-build; then
+            echo "Yarn install failed; retrying with npm fallback for constrained runner memory"
+            rm -f package-lock.json
+            npm install --ignore-scripts --no-audit --no-fund --prefer-offline
+          fi
 
-          cd backend
-          uv sync --dev
-          cd ../frontend
-          yarn install --immutable || yarn install
-
-      - name: Run pre-commit source checks
+      - name: Run frontend pre-commit source checks
         env:
           CI: "true"
         run: |
           set -euo pipefail
-          export PATH="$HOME/.local/bin:$PATH"
-          cd backend
-          uv run pre-commit run --all-files --show-diff-on-failure --config ../.pre-commit-config.yaml
+          cd frontend
+          corepack yarn eslint . --max-warnings=0
+          corepack yarn vue-tsc --noEmit
+          corepack yarn prettier --check .
 
       - *failure_diagnostics_step
 
@@ -246,7 +344,7 @@ jobs:
     name: Dispatch Downstream Build
     runs-on: ubuntu-act
     timeout-minutes: 10
-    needs: [setup, source-precommit-checks]
+    needs: [setup, source-precommit-checks-backend, source-precommit-checks-frontend]
     steps:
       - name: Identify runner
         run: |

.gitea/workflows/cicd-tests.yaml

@@ -6,6 +6,12 @@ on:
       head_sha:
         description: Commit SHA to process
         required: false
+      deployable_backend_tag_ref:
+        description: Deployable backend image tag reference
+        required: false
+      deployable_backend_digest_ref:
+        description: Deployable backend image digest reference
+        required: false
       source_workflow:
         description: Upstream workflow name
         required: false
@@ -30,6 +36,8 @@ jobs:
     timeout-minutes: 8
     outputs:
       head_sha: ${{ steps.meta.outputs.head_sha }}
+      deployable_backend_tag_ref: ${{ steps.meta.outputs.deployable_backend_tag_ref }}
+      deployable_backend_digest_ref: ${{ steps.meta.outputs.deployable_backend_digest_ref }}
     steps:
       - name: Identify runner
         run: |
@@ -48,6 +56,8 @@ jobs:
           EVENT_NAME: ${{ github.event_name }}
           SOURCE_WORKFLOW: ${{ github.event.inputs.source_workflow }}
           HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
+          DEPLOYABLE_BACKEND_TAG_REF_INPUT: ${{ github.event.inputs.deployable_backend_tag_ref }}
+          DEPLOYABLE_BACKEND_DIGEST_REF_INPUT: ${{ github.event.inputs.deployable_backend_digest_ref }}
           HEAD_SHA_FALLBACK: ${{ github.sha }}
           REF: ${{ github.ref }}
           REF_NAME: ${{ github.ref_name }}
@@ -61,6 +71,8 @@ jobs:
           echo "source_workflow=${SOURCE_WORKFLOW}"
           echo "head_sha_input=${HEAD_SHA_INPUT}"
           echo "head_sha=${RESOLVED_HEAD_SHA}"
+          echo "deployable_backend_tag_ref_input=${DEPLOYABLE_BACKEND_TAG_REF_INPUT}"
+          echo "deployable_backend_digest_ref_input=${DEPLOYABLE_BACKEND_DIGEST_REF_INPUT}"
           echo "ref=${REF}"
           echo "ref_name=${REF_NAME}"
           echo "head_ref=${HEAD_REF}"
@@ -70,10 +82,14 @@ jobs:
         id: meta
         env:
           HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
+          DEPLOYABLE_BACKEND_TAG_REF_INPUT: ${{ github.event.inputs.deployable_backend_tag_ref }}
+          DEPLOYABLE_BACKEND_DIGEST_REF_INPUT: ${{ github.event.inputs.deployable_backend_digest_ref }}
           HEAD_SHA_FALLBACK: ${{ github.sha }}
         run: |
           RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}"
           echo "head_sha=${RESOLVED_HEAD_SHA}" >> "$GITHUB_OUTPUT"
+          echo "deployable_backend_tag_ref=${DEPLOYABLE_BACKEND_TAG_REF_INPUT}" >> "$GITHUB_OUTPUT"
+          echo "deployable_backend_digest_ref=${DEPLOYABLE_BACKEND_DIGEST_REF_INPUT}" >> "$GITHUB_OUTPUT"
 
       - &failure_diagnostics_step
         name: Failure diagnostics
@@ -269,7 +285,7 @@ jobs:
       - *failure_diagnostics_step
 
   integration-tests:
-    name: Integration Tests
+    name: Runtime Black-Box Integration Tests
     # Pin integration tests to high-memory worker to reduce setup-stage runner churn.
     runs-on: ubuntu-act-8gb
     timeout-minutes: 20
@@ -288,28 +304,201 @@ jobs:
           echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 
       - *configure_registry_host_step
-      - *ensure_cicd_image_step
-      - name: Run integration tests
+      - name: Run runtime black-box integration checks
         env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
+          DEPLOYABLE_BACKEND_TAG_REF: ${{ needs.setup.outputs.deployable_backend_tag_ref }}
+          DEPLOYABLE_BACKEND_DIGEST_REF: ${{ needs.setup.outputs.deployable_backend_digest_ref }}
         run: |
+          set -euo pipefail
           set -o pipefail
-          LOG_FILE="$(mktemp)"
 
-          docker run --rm "${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}" bash -c "
-            cd /workspace/backend &&
-            source .venv/bin/activate &&
-            if [ -d 'tests/integration' ]; then
-              uv run pytest tests/integration/ -v --tb=short
-            else
-              echo 'No integration tests found'
+          RUN_ID="${GITHUB_RUN_ID:-local}"
+          RUN_ATTEMPT="${GITHUB_RUN_ATTEMPT:-1}"
+          LOG_FILE="$(mktemp)"
+          NETWORK_NAME="plex-blackbox-${RUN_ID}-${RUN_ATTEMPT}"
+          DB_CONTAINER="plex-blackbox-db-${RUN_ID}-${RUN_ATTEMPT}"
+          BACKEND_CONTAINER="plex-blackbox-backend-${RUN_ID}-${RUN_ATTEMPT}"
+          DB_PASSWORD="plex_password"
+          DB_URL="postgresql://plex_user:${DB_PASSWORD}@${DB_CONTAINER}:5432/plex_playlist"
+
+          fetch_backend_endpoint() {
+            endpoint_path="$1"
+            output_file="$2"
+            probe_tmp="$(mktemp)"
+
+            if ! docker exec "${BACKEND_CONTAINER}" python -c "$(printf '%s\n' \
+              'import sys' \
+              'import urllib.error' \
+              'import urllib.request' \
+              'endpoint_path = sys.argv[1]' \
+              'url = f"http://127.0.0.1:8000{endpoint_path}"' \
+              'try:' \
+              '    with urllib.request.urlopen(url, timeout=2) as response:' \
+              '        body = response.read().decode("utf-8", errors="replace")' \
+              '        print(response.status)' \
+              '        print(body)' \
+              'except urllib.error.HTTPError as err:' \
+              '    body = err.read().decode("utf-8", errors="replace")' \
+              '    print(err.code)' \
+              '    print(body)' \
+              'except Exception:' \
+              '    print("000")' \
+              '    print("")'
+            )" "${endpoint_path}" >"${probe_tmp}" 2>/dev/null
+            then
+              : >"${output_file}"
+              rm -f "${probe_tmp}"
+              echo "000"
+              return 0
             fi
-          " 2>&1 | tee "${LOG_FILE}"
+
+            http_code="$(head -n 1 "${probe_tmp}")"
+            tail -n +2 "${probe_tmp}" >"${output_file}"
+            rm -f "${probe_tmp}"
+            echo "${http_code}"
+          }
+
+          dump_failure_context() {
+            echo "=== Runtime Integration Failure Context ==="
+            docker ps -a || true
+            echo "--- Backend logs (tail 200) ---"
+            docker logs "${BACKEND_CONTAINER}" 2>&1 | tail -n 200 || true
+            echo "--- Database logs (tail 200) ---"
+            docker logs "${DB_CONTAINER}" 2>&1 | tail -n 200 || true
+            echo "--- Backend inspect (status/image) ---"
+            docker inspect --format '{{json .State}} {{.Image}}' "${BACKEND_CONTAINER}" || true
+            echo "--- Database inspect (status/image) ---"
+            docker inspect --format '{{json .State}} {{.Image}}' "${DB_CONTAINER}" || true
+          }
+
+          cleanup() {
+            docker rm -f "${BACKEND_CONTAINER}" >/dev/null 2>&1 || true
+            docker rm -f "${DB_CONTAINER}" >/dev/null 2>&1 || true
+            docker network rm "${NETWORK_NAME}" >/dev/null 2>&1 || true
+          }
+
+          trap cleanup EXIT
+
+          {
+            if [ -z "${DEPLOYABLE_BACKEND_TAG_REF}" ] || [ -z "${DEPLOYABLE_BACKEND_DIGEST_REF}" ]; then
+              echo "❌ Missing deployable backend image references from dispatch inputs"
+              exit 1
+            fi
+
+            echo "${{ secrets.PACKAGE_ACCESS_TOKEN }}" | docker login "http://${GITEA_REGISTRY}" -u "${{ github.actor }}" --password-stdin
+
+            docker pull "${DEPLOYABLE_BACKEND_TAG_REF}"
+            docker pull "${DEPLOYABLE_BACKEND_DIGEST_REF}"
+
+            DEPLOYABLE_BACKEND_REPO="${DEPLOYABLE_BACKEND_DIGEST_REF%%@*}"
+            EXPECTED_DIGEST_REF="${DEPLOYABLE_BACKEND_DIGEST_REF}"
+            ACTUAL_TAG_DIGEST_REF="$({
+              docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "${DEPLOYABLE_BACKEND_TAG_REF}" \
+                | grep "^${DEPLOYABLE_BACKEND_REPO}@sha256:" \
+                | head -n 1
+            } || true)"
+
+            if [ -z "${ACTUAL_TAG_DIGEST_REF}" ]; then
+              echo "❌ Could not resolve digest from tag reference: ${DEPLOYABLE_BACKEND_TAG_REF}"
+              exit 1
+            fi
+
+            if [ "${ACTUAL_TAG_DIGEST_REF}" != "${EXPECTED_DIGEST_REF}" ]; then
+              echo "❌ Tag and digest mismatch"
+              echo "expected=${EXPECTED_DIGEST_REF}"
+              echo "actual=${ACTUAL_TAG_DIGEST_REF}"
+              exit 1
+            fi
+
+            echo "Resolved deployable backend tag: ${DEPLOYABLE_BACKEND_TAG_REF}"
+            echo "Resolved deployable backend digest: ${EXPECTED_DIGEST_REF}"
+
+            docker network create "${NETWORK_NAME}"
+
+            docker run -d \
+              --name "${DB_CONTAINER}" \
+              --network "${NETWORK_NAME}" \
+              -e POSTGRES_DB=plex_playlist \
+              -e POSTGRES_USER=plex_user \
+              -e POSTGRES_PASSWORD="${DB_PASSWORD}" \
+              postgres:16-alpine
+
+            db_ready=false
+            for i in $(seq 1 30); do
+              if docker exec "${DB_CONTAINER}" pg_isready -U plex_user -d plex_playlist >/dev/null 2>&1; then
+                db_ready=true
+                break
+              fi
+              sleep 2
+            done
+            if [ "${db_ready}" != "true" ]; then
+              echo "❌ Database did not become ready"
+              dump_failure_context
+              exit 1
+            fi
+
+            docker run -d \
+              --name "${BACKEND_CONTAINER}" \
+              --network "${NETWORK_NAME}" \
+              -p 18000:8000 \
+              -e DATABASE_URL="${DB_URL}" \
+              -e ENVIRONMENT=production \
+              "${EXPECTED_DIGEST_REF}"
+
+            backend_ready=false
+            for i in $(seq 1 40); do
+              backend_running="$(docker inspect -f '{{.State.Running}}' "${BACKEND_CONTAINER}" 2>/dev/null || echo false)"
+              if [ "${backend_running}" != "true" ]; then
+                echo "❌ Backend container exited before becoming healthy"
+                dump_failure_context
+                exit 1
+              fi
+
+              health_code="$(fetch_backend_endpoint "/health" /tmp/blackbox-health.json)"
+              if [ "${health_code}" = "200" ]; then
+                backend_ready=true
+                break
+              fi
+              sleep 2
+            done
+            if [ "${backend_ready}" != "true" ]; then
+              echo "❌ Backend did not become healthy"
+              cat /tmp/blackbox-health.json 2>/dev/null || true
+              dump_failure_context
+              exit 1
+            fi
+
+            root_code="$(fetch_backend_endpoint "/" /tmp/blackbox-root.json)"
+            if [ "${root_code}" != "200" ] || ! grep -q 'Plex Playlist Backend API' /tmp/blackbox-root.json; then
+              echo "❌ Root endpoint validation failed"
+              cat /tmp/blackbox-root.json 2>/dev/null || true
+              dump_failure_context
+              exit 1
+            fi
+
+            compatibility_code="$(fetch_backend_endpoint "/compatibility" /tmp/blackbox-compatibility.json)"
+            if [ "${compatibility_code}" != "200" ] || ! grep -q '"ok":true' /tmp/blackbox-compatibility.json; then
+              echo "❌ Compatibility endpoint validation failed"
+              cat /tmp/blackbox-compatibility.json 2>/dev/null || true
+              dump_failure_context
+              exit 1
+            fi
+
+            health_code="$(fetch_backend_endpoint "/health" /tmp/blackbox-health.json)"
+            if [ "${health_code}" != "200" ] || ! grep -q '"status":"healthy"' /tmp/blackbox-health.json; then
+              echo "❌ Health endpoint validation failed"
+              cat /tmp/blackbox-health.json 2>/dev/null || true
+              dump_failure_context
+              exit 1
+            fi
+
+            echo "✅ Runtime black-box integration checks passed"
+          } 2>&1 | tee "${LOG_FILE}"
 
           TEST_STATUS=${PIPESTATUS[0]}
           if [ "${TEST_STATUS}" -ne 0 ]; then
-            echo "❌ Integration tests failed (exit=${TEST_STATUS})"
-            echo "--- Last 200 lines of integration test output ---"
+            echo "❌ Runtime black-box integration checks failed (exit=${TEST_STATUS})"
+            echo "--- Last 200 lines of runtime black-box integration output ---"
             tail -n 200 "${LOG_FILE}" || true
             exit "${TEST_STATUS}"
           fi

.gitea/workflows/docker-build-main.yaml

@@ -138,6 +138,8 @@ jobs:
     timeout-minutes: 60
     outputs:
       head_sha: ${{ steps.meta.outputs.head_sha }}
+      deployable_backend_tag_ref: ${{ steps.deployable_backend_ref.outputs.deployable_backend_tag_ref }}
+      deployable_backend_digest_ref: ${{ steps.deployable_backend_ref.outputs.deployable_backend_digest_ref }}
 
     steps:
       - name: Identify runner
@@ -251,6 +253,44 @@ jobs:
             --image deployable-frontend:"${HEAD_SHA}" \
             --profile frontend
 
+      - name: Push deployable backend runtime image
+        id: deployable_backend_ref
+        env:
+          PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
+          REGISTRY_USER: ${{ github.actor }}
+          HEAD_SHA: ${{ steps.meta.outputs.head_sha }}
+        run: |
+          set -euo pipefail
+
+          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
+            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
+          fi
+
+          echo "${PACKAGE_ACCESS_TOKEN}" | docker login "http://${GITEA_REGISTRY}" -u "${REGISTRY_USER}" --password-stdin
+
+          DEPLOYABLE_BACKEND_REPO="${GITEA_REGISTRY}/darkhelm.org/deployable-backend"
+          DEPLOYABLE_BACKEND_TAG_REF="${DEPLOYABLE_BACKEND_REPO}:${HEAD_SHA}"
+
+          docker tag "deployable-backend:${HEAD_SHA}" "${DEPLOYABLE_BACKEND_TAG_REF}"
+          docker push "${DEPLOYABLE_BACKEND_TAG_REF}"
+          docker pull "${DEPLOYABLE_BACKEND_TAG_REF}" >/dev/null
+
+          DEPLOYABLE_BACKEND_DIGEST_REF="$({
+            docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "${DEPLOYABLE_BACKEND_TAG_REF}" \
+              | grep "^${DEPLOYABLE_BACKEND_REPO}@sha256:" \
+              | head -n 1
+          } || true)"
+
+          if [ -z "${DEPLOYABLE_BACKEND_DIGEST_REF}" ]; then
+            echo "❌ Unable to resolve deployable backend digest reference"
+            exit 1
+          fi
+
+          echo "deployable_backend_tag_ref=${DEPLOYABLE_BACKEND_TAG_REF}" >> "$GITHUB_OUTPUT"
+          echo "deployable_backend_digest_ref=${DEPLOYABLE_BACKEND_DIGEST_REF}" >> "$GITHUB_OUTPUT"
+          echo "deployable_backend_tag_ref=${DEPLOYABLE_BACKEND_TAG_REF}"
+          echo "deployable_backend_digest_ref=${DEPLOYABLE_BACKEND_DIGEST_REF}"
+
       - name: Build and push complete CICD image
         env:
           PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
@@ -347,6 +387,8 @@ jobs:
           ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }}
           PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
           HEAD_SHA: ${{ needs.build.outputs.head_sha }}
+          DEPLOYABLE_BACKEND_TAG_REF: ${{ needs.build.outputs.deployable_backend_tag_ref }}
+          DEPLOYABLE_BACKEND_DIGEST_REF: ${{ needs.build.outputs.deployable_backend_digest_ref }}
           REPO_FULL: ${{ github.repository }}
           HEAD_REF: ${{ github.head_ref }}
           REF_NAME: ${{ github.ref_name }}
@@ -426,6 +468,8 @@ jobs:
             --head-sha "${HEAD_SHA}"
             --source-workflow "CICD Main Build"
             --trace-id "${TRACE_ID}"
+            --input "deployable_backend_tag_ref=${DEPLOYABLE_BACKEND_TAG_REF}"
+            --input "deployable_backend_digest_ref=${DEPLOYABLE_BACKEND_DIGEST_REF}"
           )
 
           for API_BASE in "${CANDIDATE_API_BASES[@]}"; do

.gitea/workflows/renovate.yml

@@ -215,7 +215,7 @@ jobs:
           cat > renovate-config.js << 'EOF'
           module.exports = {
             platform: 'gitea',
-            endpoint: 'https://dogar.darkhelm.org/api/v1',
+            endpoint: 'https://dogar.darkhelm.org',
             gitAuthor: 'Renovate Bot <renovate@darkhelm.org>',
             repositories: ['DarkHelm.org/plex-playlist'],
             onboarding: false,
@@ -237,36 +237,25 @@ jobs:
           RENOVATE_DRY_RUN: ${{ inputs.dry_run }}
           RENOVATE_CONFIG_FILE: renovate-config.js
           RENOVATE_PLATFORM: gitea
-          RENOVATE_ENDPOINT: https://dogar.darkhelm.org/api/v1
+          RENOVATE_ENDPOINT: https://dogar.darkhelm.org
           RENOVATE_ALLOW_INSECURE_TLS: "true"
           LOG_LEVEL: info
         run: |
           echo "=== Running Renovate Bot ==="
+          TARGET_REPO="DarkHelm.org/plex-playlist"
+          TARGET_ORG="${TARGET_REPO%%/*}"
 
-          select_token() {
-            if [ -n "${RENOVATE_TOKEN_SECRET:-}" ]; then
-              echo "${RENOVATE_TOKEN_SECRET}"
-              return 0
-            fi
-            if [ -n "${ACTIONS_TRIGGER_TOKEN:-}" ]; then
-              echo "${ACTIONS_TRIGGER_TOKEN}"
-              return 0
-            fi
-            if [ -n "${PACKAGE_ACCESS_TOKEN:-}" ]; then
-              echo "${PACKAGE_ACCESS_TOKEN}"
-              return 0
-            fi
-            return 1
-          }
-
-          if ! SELECTED_TOKEN="$(select_token)"; then
-            echo "❌ No token available for Renovate authentication"
-            echo "Configure one of: RENOVATE_TOKEN, ACTIONS_TRIGGER_TOKEN, PACKAGE_ACCESS_TOKEN"
-            exit 1
+          RENOVATE_ENDPOINT_EFFECTIVE="${RENOVATE_ENDPOINT%/}"
+          if [[ "${RENOVATE_ENDPOINT_EFFECTIVE}" == */api/v1 ]]; then
+            API_ENDPOINT="${RENOVATE_ENDPOINT_EFFECTIVE}"
+            RENOVATE_ENDPOINT_EFFECTIVE="${RENOVATE_ENDPOINT_EFFECTIVE%/api/v1}"
+          else
+            API_ENDPOINT="${RENOVATE_ENDPOINT_EFFECTIVE}/api/v1"
           fi
 
-          export RENOVATE_TOKEN="${SELECTED_TOKEN}"
-          unset SELECTED_TOKEN
+          export RENOVATE_ENDPOINT="${RENOVATE_ENDPOINT_EFFECTIVE}"
+          echo "Renovate endpoint: ${RENOVATE_ENDPOINT}"
+          echo "Preflight API endpoint: ${API_ENDPOINT}"
 
           CURL_INSECURE_FLAG=""
           if [ "${RENOVATE_ALLOW_INSECURE_TLS:-false}" = "true" ]; then
@@ -275,27 +264,71 @@ jobs:
             export NODE_TLS_REJECT_UNAUTHORIZED=0
           fi
 
-          # Validate token before starting Renovate to fail with actionable diagnostics.
-          AUTH_CHECK_STATUS=$(curl -sS -o /tmp/renovate-auth-check.json -w "%{http_code}" \
-            ${CURL_INSECURE_FLAG} \
-            -H "Authorization: token ${RENOVATE_TOKEN}" \
-            "${RENOVATE_ENDPOINT}/user" || true)
+          select_token_with_repo_access() {
+            for candidate_name in RENOVATE_TOKEN_SECRET ACTIONS_TRIGGER_TOKEN PACKAGE_ACCESS_TOKEN; do
+              candidate_value="${!candidate_name:-}"
+              if [ -z "${candidate_value}" ]; then
+                continue
+              fi
 
-          if [ "${AUTH_CHECK_STATUS}" != "200" ]; then
-            echo "❌ Renovate token authentication preflight failed (HTTP ${AUTH_CHECK_STATUS})"
-            echo "Expected a personal access token with repo/issue read-write permissions."
-            if [ -s /tmp/renovate-auth-check.json ]; then
-              echo "Response body:"
-              cat /tmp/renovate-auth-check.json || true
+              USER_STATUS=$(curl -sS -o /tmp/renovate-auth-check-user.json -w "%{http_code}" \
+                ${CURL_INSECURE_FLAG} \
+                -H "Authorization: token ${candidate_value}" \
+                "${API_ENDPOINT}/user" || true)
+
+              REPO_STATUS=$(curl -sS -o /tmp/renovate-auth-check-repo.json -w "%{http_code}" \
+                ${CURL_INSECURE_FLAG} \
+                -H "Authorization: token ${candidate_value}" \
+                "${API_ENDPOINT}/repos/${TARGET_REPO}" || true)
+
+              ORG_STATUS=$(curl -sS -o /tmp/renovate-auth-check-org.json -w "%{http_code}" \
+                ${CURL_INSECURE_FLAG} \
+                -H "Authorization: token ${candidate_value}" \
+                "${API_ENDPOINT}/orgs/${TARGET_ORG}" || true)
+
+              if [ "${USER_STATUS}" = "200" ] && [ "${REPO_STATUS}" = "200" ] && [ "${ORG_STATUS}" = "200" ]; then
+                echo "${candidate_name}:${candidate_value}"
+                return 0
+              fi
+
+              echo "⚠ Token candidate ${candidate_name} rejected (user=${USER_STATUS}, repo=${REPO_STATUS}, org=${ORG_STATUS})"
+            done
+
+            return 1
+          }
+
+          if ! SELECTED_TOKEN_RESULT="$(select_token_with_repo_access)"; then
+            echo "❌ No token available for Renovate authentication with repository access"
+            echo "Configure RENOVATE_TOKEN with repo+issue write and organization/user read scopes."
+            echo "Token preflight checks attempted: ${API_ENDPOINT}/user, ${API_ENDPOINT}/repos/${TARGET_REPO}, and ${API_ENDPOINT}/orgs/${TARGET_ORG}"
+            if [ -s /tmp/renovate-auth-check-user.json ]; then
+              echo "Last user endpoint response body:"
+              cat /tmp/renovate-auth-check-user.json || true
+            fi
+            if [ -s /tmp/renovate-auth-check-repo.json ]; then
+              echo "Last repo endpoint response body:"
+              cat /tmp/renovate-auth-check-repo.json || true
+            fi
+            if [ -s /tmp/renovate-auth-check-org.json ]; then
+              echo "Last org endpoint response body:"
+              cat /tmp/renovate-auth-check-org.json || true
             fi
             exit 1
           fi
 
-          echo "✓ Renovate auth preflight passed"
+          SELECTED_TOKEN_SOURCE="${SELECTED_TOKEN_RESULT%%:*}"
+          SELECTED_TOKEN="${SELECTED_TOKEN_RESULT#*:}"
+          export RENOVATE_TOKEN="${SELECTED_TOKEN}"
+          unset SELECTED_TOKEN RESULT_TOKEN
+
+          echo "✓ Renovate auth preflight passed with ${SELECTED_TOKEN_SOURCE}"
 
           # Run Renovate with configuration
           if [ "${RENOVATE_DRY_RUN}" = "true" ]; then
+            export RENOVATE_DRY_RUN="full"
             echo "🔍 Running in DRY-RUN mode (no changes will be made)"
+          else
+            unset RENOVATE_DRY_RUN
           fi
 
           renovate --platform "${RENOVATE_PLATFORM}" --endpoint "${RENOVATE_ENDPOINT}" DarkHelm.org/plex-playlist