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
• Merge settings: enable auto-merge and auto-delete head branch on merge (allow_auto_merge + delete_branch_on_merge). These have no org-level default — set them per-repo at provisioning.

Security & Merge Baseline

Every active repo runs the same baseline. The security half is meant to be carried by the org Code Security Configuration "Sea Haven Standard" (enforced, default_for_new_repos: all); attach it to the repo at creation so new repos inherit it instead of drifting. The merge half (allow_auto_merge, delete_branch_on_merge) is not covered by any org config and must be set per-repo.

Setting	Baseline	Mechanism
allow_auto_merge	enabled	per-repo (gh api repos/<org>/<repo> -X PATCH -F allow_auto_merge=true)
delete_branch_on_merge	enabled	per-repo (-F delete_branch_on_merge=true)
code_security (advanced security)	enabled	Sea Haven Standard config
Secret scanning + push protection	enabled	Sea Haven Standard config
Secret scanning non-provider patterns + validity checks	enabled	per-repo until added to the config
Dependabot alerts + security updates	enabled	org auto-enable default + config
CodeQL default setup	configured	per-repo (PATCH .../code-scanning/default-setup state=configured) until added to the config

Exceptions:

• Docs-only repos (e.g. engineering-handbook) skip CodeQL — there is no compiled code to scan; code_security may stay off. Secret scanning still applies.
• shoc-backend / shoc-frontend-new are excluded from org compliance tooling (see the .github org-config notes); leave their settings to the SHOC team.

To audit drift: gh api repos/<org>/<repo> --jq '{allow_auto_merge, delete_branch_on_merge, security_and_analysis}' and gh api repos/<org>/<repo>/code-scanning/default-setup --jq .state.

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

Agents and Automation

Agents and automation (CI bots, Cursor agents, scripts) do not push directly to main unless Adam has explicitly directed it for a specific action. The default path for any automated change is a branch and a PR, same as human-authored work.

GitHub Environments

HCP app repos use Environments as the deploy gate. See cicd.md.

Environment	Reviewers	Deployment branch policy	Variables
dev	none	main	DEPLOY_ROLE_ARN
prod	required	main and v*	DEPLOY_ROLE_ARN

DEPLOY_ROLE_ARN is an Environment variable, not a repo secret. Remaining SAM/CDK repos may still use AWS_DEPLOY_ROLE_ARN as a repo secret until they migrate.

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, HCP Terraform / 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, terraform, hcp, 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.

Required CI Status Check

The org ruleset requires the status check named ci / ci — the job name ci under the workflow named CI. This is what the reusable ci-typescript-cdk.yaml and ci-python-sam.yaml callers emit. If the check name in the ruleset does not match what CI actually emits, merges will be blocked by a phantom required check. Verify after any change to CI job names.

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.