Section 01 · Infrastructure & Setup

Git Repo Setup & Security

Repository configuration, branch strategy, CI/CD, and cleanliness standards

19 items 10 critical 9 recommended

This guide walks you through auditing a repository's Git setup, branch strategy, CI/CD configuration, and overall cleanliness.

The Goal: Clone-to-Running in Minutes

A new developer should be able to clone, install, and run the project without asking anyone for help. The repository should be self-documenting, secure by default, and impossible to accidentally break.

  • Runnable — clone to working app with zero manual intervention
  • Protected — branch rules enforce code review and prevent direct pushes
  • Tested — CI validates every PR with linting and tests
  • Secure — no secrets exposed in code or git history
  • Clean — proper .gitignore patterns, no stale files or cruft

Before You Start

  1. Read the project config from projects/<project-name>.yaml to get the repo field (e.g., acme-corp/acme-api)
  2. Clone the repo yourself — do NOT ask the user for evidence you can gather automatically:
    git clone [email protected]:<owner>/<repo>.git /tmp/audit-<project>-$(date +%s)
    If SSH fails, fall back to HTTPS:
    git clone https://github.com/<owner>/<repo>.git /tmp/audit-<project>-$(date +%s)
  3. Use the cloned directory as your working directory for all checks in this section
  4. Verify you have access to GitHub API (via gh CLI) for branch protection checks
  5. Clean up the clone when the section is complete

clone-and-run

GIT-001
Clone and run immediately critical

Repository can be cloned, built, and run without external system setup

“Can a new hire be running locally in under 10 minutes?”
GIT-002
Sandbox env vars ready critical

Sandbox/development environment variables provided in .env.example or .env

“Missing one key — does everything break with no explanation?”
GIT-003
Graceful failure with clear warnings recommended

Missing keys produce clear warnings with helpful error messages

“What does the app say when a required env var is missing?”

branch-protection

GIT-005
Branch protections configured critical

Protected branches with PR requirements, no force push, and documented admin bypass

“Could an engineer force-push to main right now?”

branch-strategy

GIT-006
Clean branch structure recommended

Only main/staging as long-lived branches, no dev/develop branch

“How many long-lived branches exist, and why?”
GIT-007
Feature branches for all work critical

All development work happens in feature branches via PRs

“When was the last direct commit to main?”
GIT-008
Feature branches deleted after merge recommended

Merged feature branches are promptly deleted

“How many merged branches are still sitting around?”
GIT-009
Stale branch audit recommended

Branches with no push for 30-45 days are reviewed and cleaned up

“Any branches untouched for 45+ days nobody's talking about?”

ci-cd

GIT-010
Linting configured critical

Linting tools configured locally and in CI, runs on PRs

“Does a sloppy PR actually get blocked, or just warned?”
GIT-011
Testing configured critical

Test framework configured locally and in CI, runs on PRs

“Can broken code merge if all tests are skipped?”

documentation

GIT-012
README.md present critical

Repository has a README with accurate setup instructions

“Is the README still accurate, or is it lying to new devs?”
GIT-013
AI agent context file recommended

CLAUDE.md or AGENTS.md provides context for AI agents

“Would an AI agent know what NOT to touch in this repo?”

local-dev

GIT-014
Docker Compose for services recommended

Third-party services available via Docker Compose with matching env vars

“How many external accounts does a dev need before first run?”

repo-cleanliness

GIT-015
No useless/outdated files recommended

No backup files, dated reports, or outdated planning documents

“Any files in here nobody's opened in 6 months?”
GIT-016
Test results gitignored critical

Test output, coverage reports not committed

“Are coverage reports cluttering your git history?”
GIT-017
No credentials in repo critical

No production secrets in repository or git history

“Searched git history for secrets lately — really searched?”
GIT-018
Sandbox keys rotation documented recommended

Sandbox keys have rotation schedule and last rotation date in comments

“When were the sandbox keys last rotated — do you know?”
GIT-019
No local engineer settings recommended

IDE configs and personal settings not committed

“Is someone's .vscode/ or .idea/ folder in this repo?”
GIT-020
Proper .gitignore configured critical

.gitignore covers all standard patterns for the project type

“How confident are you nothing sensitive slips through?”
Next section →

Dependencies & Code Quality

7 items