mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 05:43:15 +00:00
Document README badges, repo topics, and PR auto-labeler conventions (INFRA-56/57/70)
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:
parent
144240884b
commit
a4742fc97b
2 changed files with 42 additions and 0 deletions
23
cicd.md
23
cicd.md
|
|
@ -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
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -4,6 +4,7 @@
|
|||
|
||||
- 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
|
||||
|
|
@ -95,6 +96,24 @@ updates:
|
|||
- 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue