From 55aabaa325eaba8627cfb0b5aa4d17893ba533ea Mon Sep 17 00:00:00 2001 From: efiten Date: Thu, 3 Sep 2026 19:16:43 +0200 Subject: [PATCH] ci: skip the pipeline for documentation-only changes (#1949) Two documentation-only PRs were running the full pipeline simultaneously this afternoon: #1948 (`CHANGELOG.md` plus a release note) and #1947 (deleting a stale `docs/DEPLOYMENT.md`). Each spends about 12 minutes on Go Build & Test and about 16 minutes on Playwright to establish that a text file does not break a browser. **The cost is the queue, not the minutes.** On the same afternoon a `pull_request` run was created at 12:13 and its first job did not start until 16:19. Four hours in the queue. Every unnecessary run pushes the ones that matter further back, and this repository has been merging heavily today. ## Checked before adding the filter Rather than assumed: - **Nothing reads markdown at build or test time.** Grepping every Go and JS source for a runtime read (`ReadFile`, `readFileSync`, `os.Open`) of a `.md` path returns nothing. The `docs/` matches in `cmd/` and `test-*.js` are all comments pointing at documentation. - `/api/docs` serves Swagger UI generated from `cmd/server/openapi.go`, not from `docs/`. - `docs/` holds markdown plus screenshots (`png`, `gif`) and no build input. - **This workflow has no tag trigger**, so release tagging is unaffected; that runs from `release-fast-path.yml`. Worth stating explicitly given a `v3.10.0` tag is imminent. `paths-ignore` skips only when **every** changed file matches, so a PR touching both code and documentation still runs the full pipeline. ## The trap, stated in the file If required status checks are ever enabled on master, a skipped workflow never reports, and a docs-only PR would wait forever on a check that cannot arrive. At that point this needs to become a change-detection job with conditional heavy jobs rather than a trigger filter. Master has no required checks today. Verified: the branch protection endpoint returns 404. That caveat is in a comment above the `on:` block, not just in this description, because the person who enables required checks in six months will be reading the workflow and not this PR. ## Note This PR itself changes only `.github/workflows/deploy.yml`, so it is not documentation-only and will run the full pipeline, as it should. Co-authored-by: Claude Opus 5 (1M context) --- .github/workflows/deploy.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 8228b867..da59c0ae 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,10 +1,33 @@ name: CI/CD Pipeline +# Documentation-only changes skip this pipeline entirely. Nothing under +# docs/ or any *.md file is read at build or test time: no Go or JS source +# opens one, and /api/docs serves Swagger generated from openapi.go, not +# from docs/. Running a 16-minute Playwright suite to prove that a +# markdown file does not break the browser only pushed the runs that do +# matter further down a queue that has been hours deep. +# +# paths-ignore skips only when EVERY changed file matches, so a PR that +# touches both code and docs still runs the full pipeline. +# +# Caveat if required status checks are ever enabled on master: a skipped +# workflow never reports, so a docs-only PR would wait forever on a check +# that cannot arrive. At that point this needs to become a change-detection +# job with conditional heavy jobs, not a trigger filter. There are no +# required checks on master today. on: push: branches: [master] + paths-ignore: + - '**/*.md' + - 'docs/**' + - 'LICENSE' pull_request: branches: [master] + paths-ignore: + - '**/*.md' + - 'docs/**' + - 'LICENSE' workflow_dispatch: permissions: