beaus-tolling

GitHub Governance

Repository Standards

This repository is expected to operate like a production platform repository, not an informal project repo.

Required Baseline

• main and staging branches
• protected branches
• pull-request-only change flow
• CODEOWNERS
• release notes automation
• dependency update automation
• security scanning on pull requests and protected branches
• conventional commit discipline

Files Included in This Repository

• .github/workflows/ci.yml
• .github/workflows/dependency-review.yml
• .github/workflows/codeql.yml
• .github/workflows/secret-scan.yml
• .github/workflows/release-drafter.yml
• .github/workflows/deploy-staging.yml
• .github/workflows/deploy-production.yml
• .github/workflows/review-reminder.yml
• .github/CODEOWNERS
• .github/pull_request_template.md
• .gitmessage.txt
• .githooks/commit-msg
• tools/github/configure-repository.sh
• tools/github/bootstrap-teams.sh
• tools/github/configure-environments.sh
• tools/github/seed-placeholder-config.sh
• tools/github/apply-branch-protection.sh

What Still Requires GitHub Access

Because branch protection and environment protection live in GitHub itself, the following steps must be run against a real remote repository:

1. create or connect the remote repository
2. push the initial commit
3. bootstrap or map CODEOWNERS owners
4. create GitHub environments and deployment approvals
5. seed repository variables and placeholder secrets
6. run branch protection with gh authenticated as a repository admin
7. enable merge queue and required deployments if supported by the plan tier

Plan Constraints

This repository is currently designed to run on the lowest-cost GitHub footprint possible. That choice has a real trade-off:

• private repositories on GitHub Free do not expose the full branch protection API
• required deployment reviewers for GitHub Environments are not available
• environment deployment branch policies are not available

For a tolling platform that should remain private, the practical recommendation is:

1. keep the repository private
2. upgrade the organization to GitHub Team before relying on enforced release approvals
3. keep the bootstrap scripts in this repository as the source of truth so those controls can be applied immediately after the plan upgrade

Bootstrap Order

For a new repository, run:

1. bash tools/github/configure-repository.sh <owner>/<repo>
2. bash tools/github/bootstrap-teams.sh <owner> <owner>/<repo> if the owner is an organization
3. bash tools/github/configure-environments.sh <owner>/<repo>
4. bash tools/github/seed-placeholder-config.sh <owner>/<repo>
5. bash tools/github/apply-branch-protection.sh <owner>/<repo>

This sequence makes the repository usable immediately while still leaving sensitive deployment values as explicit placeholders that can be filled during infrastructure onboarding.

For personal public repositories used to publish GitHub Pages:

• use individual-user CODEOWNERS, not organization teams
• keep the repo public so Pages can be served without additional platform cost
• publish Pages from main/docs

Merge Queue Guidance

If GitHub merge queue is available on the target plan, enable it for main. It reduces broken protected branches by validating the merge result before it lands.

If merge queue is not available, keep main protected with strict status checks and use staging as the only merge source for production promotion.