fix(ci): skip docker-build validation for non-docker-relevant PRs

[LucasSantana-Dev]

Summary

docker-build (the 4-service Docker image matrix in ci.yml) is the critical-path bottleneck of the whole CI run — measured at 419s for the bot image alone (of a ~644s total run), dominated by @discordjs/opus's native compile (node-gyp/C toolchain, no prebuilt binary for the current ABI). It runs unconditionally on every pull_request/merge_group event, with no paths: filter — unlike docker-publish.yml (the workflow that builds and pushes the real release images), which already gates on one.

Adds a detect-docker-changes job that diffs the PR against its base and mirrors docker-publish.yml's existing filter (packages/**, prisma/**, Dockerfile*, nginx/**, package*.json) — plus ci.yml itself, so edits to the docker-build job definition stay validated. docker-build-check (the required branch-protection status check, "Build — Docker images") still always runs and explicitly reports success when skipped, so a required check never goes missing/pending — it just reports fast instead of waiting on a build that couldn't have been affected.

This came out of a 4-lens debate (feasibility / production-safety / pragmatism / architecture) on how to speed up CI — full synthesis available on request. This is Phase 1 (the converged, zero-risk win). Phase 2 is a follow-up: root-causing whether cache-from/cache-to: type=gha is actually landing cache hits on the expensive native-compile layer for PRs that do touch Docker-relevant paths — that's independent of this change and still TBD.

Test plan

• python3 -c "import yaml; yaml.safe_load(...)" — valid YAML
• actionlint .github/workflows/ci.yml — 0 issues
• Verified detection logic against the actual file lists of 5 recently-merged/open PRs in this repo (all 5 correctly classified RELEVANT — they all touch packages/, Dockerfile, package.json, or ci.yml itself) and 2 synthetic docs-only / .env.example-only diffs (both correctly classified SKIP)
• Live CI run on this PR itself will be the first real end-to-end validation (this PR touches only ci.yml, which the filter explicitly always treats as relevant, so docker-build will still run here — by design, since I'm changing the job that gates it)

---

Summary by cubic

Skip the 4-image docker-build matrix for PRs without Docker-relevant changes to cut CI time. The required check now skips only after successful detection and uses the merge-base to avoid false positives.

• Refactors

  • Added detect-docker-changes that diffs PRs against the merge-base and mirrors docker-publish.yml filters: packages/**, prisma/**, Dockerfile*, nginx/**, package*.json, plus .github/workflows/ci.yml.
  • Run docker-build only on pull_request/merge_group when relevant; keep docker-build-check always on with an early success when irrelevant.
  • Added ADR: decisions/2026-07-08-ci-docker-build-paths-filter-phased-speedup.md.

• Bug Fixes

  • docker-build-check now verifies detect-docker-changes completed successfully and fails if it didn’t, preventing false “skip” passes.

^{Written for commit 455e895. Summary will update on new commits.}

Summary by CodeRabbit

• Chores
  • Improved CI efficiency by running Docker-related build checks only when Docker-impacting files change.
  • Added change detection so unrelated updates skip expensive Docker jobs.
  • Preserved Docker validation while allowing it to complete quickly when no relevant changes are present.
• Documentation
  • Added an architecture decision record outlining the CI Docker build-speedup plan, including a phased rollout and future follow-up criteria.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a detect-docker-changes CI job that filters Docker/build-related changes to gate docker-build, updates docker-build-check to skip validation when the gate is false, and adds an ADR describing the phased rollout and follow-up plan.

Changes

CI Docker Build Gating

Layer / File(s)	Summary
Docker change detection and gating .github/workflows/ci.yml	Adds detect-docker-changes to compute a relevant output from changed paths, gates docker-build on that output, and makes docker-build-check skip validation when no relevant changes are detected.
Phased speedup decision record decisions/2026-07-08-ci-docker-build-paths-filter-phased-speedup.md	Adds an ADR covering the measured CI timing breakdown, the Phase 1 gating approach, Phase 2 diagnostics, rejected alternatives, consequences, and revisit criteria.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GitHub Actions as CI Workflow
  participant detect-docker-changes as detect-docker-changes
  participant docker-build as docker-build
  participant docker-build-check as docker-build-check

  GitHub Actions->>detect-docker-changes: checkout and diff changed paths
  detect-docker-changes->>detect-docker-changes: match Docker/build patterns
  detect-docker-changes-->>GitHub Actions: relevant=true/false
  GitHub Actions->>docker-build: run when relevant=true
  GitHub Actions->>docker-build-check: evaluate build result
  docker-build-check->>docker-build-check: skip when relevant!=true

Loading

Possibly related PRs

• LucasSantana-Dev/Lucky#462: Uses similar Docker-relevant path filtering to skip Docker-related workflow steps.
• LucasSantana-Dev/Lucky#1061: Modifies the same docker-build/docker-build-check CI gating structure.
  Suggested reviewers: cubic-dev-ai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: skipping docker-build validation for PRs without Docker-relevant changes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ci-docker-build-paths-filter

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Failed to generate code suggestions for PR

[cubic-dev-ai]

All reported issues were addressed across 1 file

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/ci.yml (1)

291-303: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Fail-open: an upstream detection failure silently skips Docker build validation.

The early-exit at Lines 296-299 only checks needs.detect-docker-changes.outputs.relevant, not the job's result. If detect-docker-changes itself fails (checkout error, unreachable/garbage-collected base SHA, transient runner issue, git diff erroring under the default set -e/pipefail run shell), outputs.relevant is empty — which satisfies != "true" and exits 0. The required docker-build-check status then reports success without ever validating the Docker build, defeating the whole purpose of a required check. This is a new failure mode introduced by this PR (previously docker-build-check always ran real validation).

🛡️ Fail-safe fix

         steps:
             - name: Assert all builds passed
               run: |
+                  if [[ "${{ needs.detect-docker-changes.result }}" != "success" ]]; then
+                      echo "Docker change detection did not complete cleanly (result: ${{ needs.detect-docker-changes.result }}) — failing safe."
+                      exit 1
+                  fi
                   if [[ "${{ needs.detect-docker-changes.outputs.relevant }}" != "true" ]]; then
                       echo "No Docker-relevant changes in this diff — skipping validation."
                       exit 0
                   fi
                   if [[ "${{ needs.docker-build.result }}" != "success" ]]; then
                       echo "Docker build result: ${{ needs.docker-build.result }}"
                       exit 1
                   fi

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 291 - 303, The Docker validation gate
in the workflow is fail-open because `Assert all builds passed` only checks
`needs.detect-docker-changes.outputs.relevant` and ignores whether
`detect-docker-changes` actually succeeded. Update the logic in this job to also
inspect `needs.detect-docker-changes.result` (alongside
`needs.docker-build.result`) so any upstream detection failure causes the check
to fail instead of exiting 0, while still allowing a clean skip only when
`detect-docker-changes` completed successfully and reported no relevant changes.

🧹 Nitpick comments (2)

.github/workflows/ci.yml (2)

217-219: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Consider persist-credentials: false on this checkout.

This job only reads git history to diff paths; it doesn't need the checked-out credential to persist for later git operations against GitHub.

🔒 Hardening suggestion

             - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
               with:
                   fetch-depth: 0
+                  persist-credentials: false

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 217 - 219, The checkout in the CI
workflow should not persist GitHub credentials because this job only needs
read-only history access. Update the actions/checkout step in the workflow to
set persist-credentials to false alongside fetch-depth: 0 so the job can still
diff paths without leaving reusable credentials in the workspace.

Source: Linters/SAST tools

---

296-296: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Prefer env: over direct expression interpolation in the shell script.

needs.detect-docker-changes.outputs.relevant is currently only ever "true"/"false" set by this same workflow, so this isn't exploitable today, but passing it through env: avoids any future risk if the output's provenance changes and satisfies the static-analysis rule directly.

♻️ Suggested pattern

         steps:
             - name: Assert all builds passed
+              env:
+                  DOCKER_RELEVANT: ${{ needs.detect-docker-changes.outputs.relevant }}
               run: |
-                  if [[ "${{ needs.detect-docker-changes.outputs.relevant }}" != "true" ]]; then
+                  if [[ "$DOCKER_RELEVANT" != "true" ]]; then

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml at line 296, The shell conditional in the CI
workflow is interpolating needs.detect-docker-changes.outputs.relevant directly
inside the script, which should be passed through env instead. Update the
workflow job that contains this check to bind that output to an environment
variable first, then reference the env var in the shell command; keep the logic
in the same step and use the existing detect-docker-changes output name so the
behavior stays unchanged while satisfying the static-analysis rule.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 223-224: The PR diff calculation in the CI workflow is using the
pull request base SHA directly, which can drift from the true common ancestor
and include unrelated changes. Update the step that sets BASE_SHA and runs git
diff in the workflow to compute the merge-base from the fetched base ref for
pull request runs, while still using github.event.merge_group.base_sha for
merge-queue runs. Keep the CHANGED file detection logic the same, but ensure it
diffs against the merge-base rather than the raw base SHA.

---

Outside diff comments:
In @.github/workflows/ci.yml:
- Around line 291-303: The Docker validation gate in the workflow is fail-open
because `Assert all builds passed` only checks
`needs.detect-docker-changes.outputs.relevant` and ignores whether
`detect-docker-changes` actually succeeded. Update the logic in this job to also
inspect `needs.detect-docker-changes.result` (alongside
`needs.docker-build.result`) so any upstream detection failure causes the check
to fail instead of exiting 0, while still allowing a clean skip only when
`detect-docker-changes` completed successfully and reported no relevant changes.

---

Nitpick comments:
In @.github/workflows/ci.yml:
- Around line 217-219: The checkout in the CI workflow should not persist GitHub
credentials because this job only needs read-only history access. Update the
actions/checkout step in the workflow to set persist-credentials to false
alongside fetch-depth: 0 so the job can still diff paths without leaving
reusable credentials in the workspace.
- Line 296: The shell conditional in the CI workflow is interpolating
needs.detect-docker-changes.outputs.relevant directly inside the script, which
should be passed through env instead. Update the workflow job that contains this
check to bind that output to an environment variable first, then reference the
env var in the shell command; keep the logic in the same step and use the
existing detect-docker-changes output name so the behavior stays unchanged while
satisfying the static-analysis rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 14cb525d-8c54-4d9e-9ff0-4db0867df056

📥 Commits

Reviewing files that changed from the base of the PR and between ba20cd8 and f889044.

📒 Files selected for processing (2)

• .github/workflows/ci.yml
• decisions/2026-07-08-ci-docker-build-paths-filter-phased-speedup.md

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Auto-approved: CI config change that adds path filtering to skip docker builds on non-docker PRs, with no application logic or infrastructure changes.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Auto-approved: CI workflow optimization: adds Docker-relevant change detection to skip unnecessary builds; no application logic changes.

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud