ci: skip CI for docs-only pull requests

[aryanku-dev]

What

Skip the Buildkite CI suite on pull requests that change only documentation (*.md, *.txt, README*, LICENSE, docs/**). Same mechanism already shipped for percy-api (percy/percy-api#6355).

How

Buildkite resolves if:/skip: at upload time, so a runtime git diff can't drive them — hence a dynamic (nested) upload:

• .buildkite/pipeline.yml → small bootstrap step that runs the gate script.
• .buildkite/pipeline.steps.yml → the previous full pipeline, moved verbatim (identical git blob — this is a pure move, not a rewrite).
• .buildkite/scripts/upload-pipeline.sh → diffs the PR vs its base and uploads the full pipeline unless the change is docs-only.

Safety

• Only PR builds are eligible. Every non-PR build (branch / merge / tag, incl. master and any deploy branch) always runs the full pipeline — deploys are never gated on docs detection.
• Fail-safe: any non-docs path, an empty diff, or an uncomputable diff → full pipeline.
• Bootstrap step auto-retries on agent loss (-1 / 125 / 255).

Verify before merge

1. This repo's Buildkite step uploads .buildkite/pipeline.yml (the default). If the pipeline is defined inline in the BK UI instead, the bootstrap is a no-op (harmless).
2. The required GitHub check is the overall buildkite/<pipeline> build status (a docs-only build passes green). If a specific per-step context is required, we'd add a synthetic pass.

Left as draft until the two points above are confirmed.

🤖 Generated with Claude Code

[aryanku-dev]

Claude Code PR Review

PR: #53 • Head: f1f98b1 • Reviewers: stack:pr-review (direct)

Summary

CI-only change: bootstrap pipeline conditionally uploads the full pipeline, skipping CI for docs-only PRs; gate is shell-safe and fail-safe, and the full pipeline is a verified byte-identical move.

Review Table

Priority	Category	Check	Status	Notes
Critical	Security	No hardcoded secrets/credentials	Pass	No secrets; only Buildkite env vars read.
Critical	Security	Authorization / access control enforced	N/A	CI config; no app authz surface.
High	Security	Input validation on external input	Pass	Env vars quoted and defaulted; git diff output only pattern-matched, not eval'd.
High	Security	No IDOR / object-level access gaps	N/A	No object references.
Critical	Security	No SQL injection / query interpolation	N/A	No SQL.
High	Correctness	Logic correct; edge cases handled	Pass	Grep inverted-match logic correct; deploy-branch + empty-diff + non-docs all route to full CI.
High	Correctness	Error handling present and sensible	Pass	set -uo pipefail; git fetch/git diff guarded with `
High	Concurrency	No race conditions / unsafe shared state	N/A	Single-shot bootstrap script; no shared state.
High	Testing	Tests present for new logic	N/A	Buildkite pipeline/shell gate; repo has no CI-config test harness and none is conventional here.
Medium	Testing	Error paths / edge cases tested	N/A	See above; fail-safe branches are self-documenting.
High	Testing	No regressions to existing behavior	Pass	Full pipeline moved byte-identical (blob 30fd77e -> 30fd77e); default/deploy branches always run full CI.
Medium	Performance	No N+1 / unbounded fetch	Pass	Single shallow git fetch of base ref; bounded.
Medium	Performance	Background jobs / async handled	N/A	None.
High	Maintainability	Follows existing patterns	Pass	Bootstrap+retry pattern mirrors percy-api#6355; retry exit codes match full pipeline.
Medium	Maintainability	Focused, minimal change	Pass	Three files, scope limited to CI gating.
Medium	Readability	Meaningful names, no dead code	Pass	Clear function/var names; no dead code.
Low	Readability	Comments explain "why" not "what"	Pass	Header comment explains gate rationale and fail-safe intent.
Medium	Dependencies	No unnecessary dependencies added	Pass	Uses only bash, git, buildkite-agent (already present).

Findings

None.

---

Verdict: PASS