engineering-handbook/github-standards.md

GitHub Standards

Repository Defaults

• Default branch: main
• Every repo gets a one-line description
• 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

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.