Skip to content

0002 — CI Safety Mechanisms and Direct Push Guard

Date: 2026-03-06 Status: Accepted

Context

The repository started with direct pushes to main. As it grows into a curated knowledgebase of AI tooling patterns, unreviewed changes create risk: inconsistent quality, undocumented structural decisions, and no checkpoint before content becomes canonical.

The goal is a lightweight flow with enough friction to encourage discipline: feature branch → PR → automated checks → merge.

GitHub branch protection (which would enforce this as a hard gate) requires GitHub Pro or Team for private repositories. This repo is private and will remain so. Paying for branch protection on a personal knowledgebase is not worth the cost.

Decision

Adopt a two-layer model: noise-based deterrence (not hard blocking) plus local quality gates.

Layer 1: GitHub Actions (CI — runs on every PR and push)

adr-check: When a PR touches any tool directory (claude/, cursor/, windsurf/, gemini/), it must include a new decisions/NNNN-*.md file. Soft gate — bypassable with skip-adr label for minor, non-structural changes.

markdown-lint: All *.md files must pass markdownlint-cli2 with the shared .markdownlint.yml config. Runs on PRs and on all branch pushes.

direct-push-guard: Fires on every push to main. Queries the GitHub API to check whether the pushed commit is associated with a merged PR. If not — opens a GitHub Issue assigned to the pusher with a loud title and instructions. This is not a block; it is a visible, persistent, assigned paper trail that demands acknowledgement (close with a note, or revert and redo via PR).

Layer 2: pre-commit (local quality gate)

.pre-commit-config.yaml runs locally before every commit:

  • trailing-whitespace
  • end-of-file-fixer
  • check-merge-conflict
  • markdownlint (same config as CI — catches failures before push)

Bot Identity

PRs opened by Claude (via MCP or GitHub Actions workflows) use the phazeight-ai-agent GitHub App. PRs show as opened by phazeight-ai-agent[bot]; Luke approves as the human in the loop.

Setup guide: claude/patterns/github-app-bot-setup.md

Consequences

Positive:

  • ADRs are required for structural changes, creating a self-documenting change history
  • Pre-commit catches formatting issues locally before they hit CI
  • Direct pushes to main are immediately surfaced as assigned GitHub Issues — hard to ignore, requires deliberate acknowledgement
  • Zero ongoing cost

Negative / trade-offs:

  • Direct pushes are not technically blocked — the guard is friction, not a wall
  • skip-adr and closing the issue both require discipline not to overuse
  • The direct-push-guard produces a false alarm on PR merges if the GitHub API returns no associated PR (rare edge case — close the issue and move on)

Alternatives Considered

  • GitHub Pro branch protection ($4/month): Hard block on direct pushes, required status checks. Rejected — not worth the cost for a personal repo.
  • Make repo public (free branch protection): Rejected — repo will contain private patterns and sensitive configuration over time.
  • Honor system only, no guard workflow: Rejected — no feedback loop when the flow is bypassed; the issue + email notification provides the necessary friction.
  • Hard ADR enforcement (no bypass): Rejected — too rigid for trivial content changes.