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):**

```yaml
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`:

```yaml
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:

```yaml
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](cicd.md#github-environments).

| 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.

Converted HCP CD callers pin OIDC with both claims: `job_workflow_ref` on the org reusable (`cd-hcp-fargate.yaml` / `cd-hcp-spa.yaml`) and `workflow_ref` on the thin repo caller at `refs/heads/main` and `refs/tags/v*`. `sub` stays `repo:.../<app>:environment:<env>`. Details are in [cicd.md](cicd.md#github-deploy-role).

## 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

Two org rulesets. A repo is on exactly one of them. Never both.

| Ruleset | Required check | Who |
|---|---|---|
| **main branch protection** | `ci / ci` | Unconverted remaining-lane repos |
| **CI complete** | `ci-complete` | Converted HCP callers |

`CI complete` starts with no repos. Flip include/unexclude in the same window as the workflow merge that lands `name: ci-complete`. Do not put portion names (`frontend / static`, `unit (1)`, `browser-smoke`) in a ruleset.

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.

Mergify YAML is not used. Converted CI keeps a `merge_group` trigger so native GitHub merge queues still run. Do not treat a missing Mergify config as a gap. Do not remove or retarget native GitHub merge-queue rulesets when flipping CI membership.

The formatter GitHub App is not on the main-branch ruleset bypass list.

## 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.