engineering-handbook/github-standards.md

GitHub Standards

Repository Defaults

• Default branch: main
• Every repo gets a one-line description
• Every repo gets standard topics and a README badge block (see below)
• Default to private visibility for org repos
• Dependabot alerts and security updates enabled on all active repos
• Org-level defaults auto-enable alerts and security updates on new repos
• Every repo with dependencies gets a .github/dependabot.yml for weekly version updates

Dependabot Configuration

Every active repo with package dependencies must have a .github/dependabot.yml that covers all relevant ecosystems.

Pinning Principle

Exact pins are for reproducibility, not for freezing time. The pinned version is kept current by Dependabot version updates gated by CI and dependency review — never by a version number written in documentation.

• Never add a blanket ignore entry for a dependency. If a specific release is broken, ignore that release only (versions: ["x.y.z"]), with a comment, and remove the entry once a fixed release ships.
• Never dismiss a vulnerability alert as "waiting for upstream" without a linked follow-up that advances the pin when the fix ships.
• If a bump PR fails CI, the gate worked — leave the bad release unmerged and take the next one.

Ecosystem Selection

Choose ecosystems based on what dependency files exist in the repo:

File	Ecosystem
package.json	npm
requirements.txt	pip
.csproj	nuget
.github/workflows/*.yml	github-actions

Standard Templates

Single ecosystem (npm or pip):

version: 2
updates:
  - package-ecosystem: "npm"  # or "pip", "nuget", "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

SAM project with per-function requirements.txt:

Add a separate entry for each directory containing a requirements.txt:

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/src/processor"
    schedule:
      interval: "weekly"
  - package-ecosystem: "pip"
    directory: "/src/receiver"
    schedule:
      interval: "weekly"

Mixed ecosystems (e.g., CDK in JS with Python Lambdas, or repos with GitHub Actions):

Add one entry per ecosystem/directory:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
  - package-ecosystem: "pip"
    directory: "/src"
    schedule:
      interval: "weekly"
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Merging Dependabot PRs

• Patch and minor bumps: Safe to merge without review in most cases
• Major version bumps: Review changelog for breaking changes before merging
• When merging multiple Dependabot PRs, merge one at a time — subsequent PRs will auto-rebase

Branch Protection

• Require a PR for merges to main (no direct push)
• No force push to main
• No branch deletion for main

README Badges

Every repo's README carries a small badge block immediately under the H1. Use static badges only — dynamic badges (for example shields.io last-commit or open-issues) query the public GitHub API and render broken on private repos.

• CI status: the GitHub-native workflow badge (.../actions/workflows/<ci-file>/badge.svg), and only when a CI workflow exists. On private repos it renders only for logged-in org members — that is accepted.
• Stack: two to four static shields.io badges for the language and IaC/runtime (Python / TypeScript / .NET, AWS SAM / CDK), plus a Slack badge when the repo integrates Slack.
• Keep badges static so they never go stale; version-pinned badges drift.

Repository Topics

Every repo gets a set of lowercase, hyphenated topics so the org is filterable by stack and purpose. Draw from a consistent vocabulary:

• Cloud / IaC: aws, sam, cdk, lambda, ec2, s3, cloudfront
• Language: python, typescript, javascript, dotnet, react, nodejs
• Integration / domain: slack, bedrock, ai, security, internal-tool, documentation

Set them with gh repo edit <repo> --add-topic a,b,c. Adding topics is part of new-repo provisioning, not a follow-up.

Repo Hygiene

• Delete feature branches after merge
• Archive repos that are no longer actively developed (close issues first)
• Don't delete repos unless truly disposable
• Scrub all company-specific info from git history before making any repo public

Public Repos

Before making a repo public, verify the entire git history contains no:

• Phone numbers or customer data
• API subdomains or internal URLs
• Webhook endpoints
• Employee names or internal identifiers

If sensitive data was committed at any point, start fresh with a clean git init rather than rewriting history.