Document README badges, repo topics, and PR auto-labeler conventions (INFRA-56/57/70) (#14)

Capture the org conventions rolled out in the INFRA-47 hygiene pass:
- github-standards.md: static-only README badges (dynamic shields break on
  private repos; CI badge is member-only) and a lowercase-hyphenated repo
  topic vocabulary, both part of new-repo provisioning.
- cicd.md: the central inline-config reusable PR labeler — pull_request
  trigger, the three required caller permissions, no per-repo labeler.yml.
This commit is contained in:
Adam Moussa 2026-06-11 14:25:12 -04:00 • committed by GitHub
parent 144240884b
commit 132e4fe51d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 42 additions and 0 deletions

23
cicd.md
View file

@ -96,3 +96,26 @@ Always pass `node-version: "24"` to reusable workflows. Local dev uses Node 24 /
- When working on an existing project that lacks one — flag it and add it as part of the current work - When working on an existing project that lacks one — flag it and add it as part of the current work
A project is not production-ready without CI/CD. A project is not production-ready without CI/CD.
## PR Auto-Labeling
Pull requests are auto-labeled org-wide by a reusable workflow in `.github`. The label rules live once, centrally, inside the reusable workflow itself (written to the runner at execution time), so each repo needs only a short caller and **no per-repo `labeler.yml`**:
```yaml
# .github/workflows/labeler.yml — the per-repo caller
name: Labeler
on:
pull_request:
branches: [main]
permissions:
contents: read
pull-requests: write
issues: write
jobs:
label:
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@main
```
- The trigger is plain `pull_request`, not `pull_request_target`: private repos take no fork PRs, so the lower-privilege event is sufficient and avoids the pwn-request surface. Because `pull_request` runs the workflow from the merge commit, the Labeler check appears on the PR that first adds the caller — an absent or failed check means a missing permission, not expected behaviour.
- The caller MUST grant all three permissions. Reusable-workflow permissions can only be downgraded from the caller, so omitting `issues: write` (needed to create labels that don't exist yet) or any other grant causes a silent `startup_failure`.
- Adding the caller is part of new-repo provisioning.

View file

@ -4,6 +4,7 @@
- Default branch: `main` - Default branch: `main`
- Every repo gets a one-line description - 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 - Default to `private` visibility for org repos
- Dependabot alerts and security updates enabled on all active repos - Dependabot alerts and security updates enabled on all active repos
- Org-level defaults auto-enable alerts and security updates on new repos - Org-level defaults auto-enable alerts and security updates on new repos
@ -95,6 +96,24 @@ updates:
- No force push to `main` - No force push to `main`
- No branch deletion for `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 ## Repo Hygiene
- Delete feature branches after merge - Delete feature branches after merge