diff --git a/cicd.md b/cicd.md index 176a6ba..0d746ec 100644 --- a/cicd.md +++ b/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. diff --git a/github-standards.md b/github-standards.md index adf9feb..e96c774 100644 --- a/github-standards.md +++ b/github-standards.md @@ -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//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 --add-topic a,b,c`. Adding topics is part of new-repo provisioning, not a follow-up. + ## Repo Hygiene - Delete feature branches after merge