diff --git a/standards/ci-standards.md b/standards/ci-standards.md index 499ac48..fbb506d 100644 --- a/standards/ci-standards.md +++ b/standards/ci-standards.md @@ -14,16 +14,40 @@ repository must implement. > templates are the source of truth — anything generated from scratch is, by > definition, drift. -Available templates: - -| Template | Purpose | -|----------|---------| -| [`agent-shield.yml`](workflows/agent-shield.yml) | Deep agent-config security scan via `ecc-agentshield` | -| [`claude.yml`](workflows/claude.yml) | Thin caller delegating to the org-level reusable Claude Code workflow | -| [`dependabot-automerge.yml`](workflows/dependabot-automerge.yml) | Auto-approve and squash-merge eligible Dependabot PRs | -| [`dependabot-rebase.yml`](workflows/dependabot-rebase.yml) | Rebase Dependabot PRs on demand | -| [`dependency-audit.yml`](workflows/dependency-audit.yml) | Multi-ecosystem audit (npm, pnpm, gomod, cargo, pip) | -| [`feature-ideation.yml`](workflows/feature-ideation.yml) | BMAD Method ideation pipeline (BMAD-enabled repos only) | +### Centralization tiers + +Every standard workflow falls into one of three tiers. Knowing the tier tells +you how much of the file you may edit when adopting it in a new repo, and +where to send a fix when behavior needs to change. + +| Tier | Examples | What lives in `standards/workflows/` | Where logic lives | Edits allowed in adopting repo | +|---|---|---|---|---| +| **1. Stub** | `claude.yml`, `dependency-audit.yml`, `dependabot-automerge.yml`, `dependabot-rebase.yml`, `agent-shield.yml`, `feature-ideation.yml` | A thin caller stub that delegates via `uses: petry-projects/.github/.github/workflows/-reusable.yml@v1` | The matching `*-reusable.yml` in this repo (single source of truth) | **None** in normal use. May tune `with:` inputs where the reusable exposes them (e.g. `agent-shield` accepts `min-severity`, `required-files`; `feature-ideation` requires `project_context`). To change behavior, open a PR against the reusable in this repo — the change propagates everywhere on next run. | +| **2. Per-repo template** | `ci.yml`, `codeql.yml`, `sonarcloud.yml` | _(no template — see the patterns documented below)_ | In each repo, because the workflow is tech-stack-specific (language matrix, build tool, test framework) | **Limited.** Each adopting repo carries its own copy. Stay within the patterns in this document; do not change action SHAs, permission scopes, trigger events, or job names without raising a standards PR first. | +| **3. Free per-repo** | `release.yml`, project-specific automation | _(out of scope for this standard)_ | Per-repo | Free, but must still comply with the [Action Pinning Policy](#action-pinning-policy) and the [Required Workflows](#required-workflows) constraints. | + +Tier 1 stubs all carry an identical `SOURCE OF TRUTH` header block telling +agents what they may and may not edit. If you're considering modifying a +file with that header, **stop and read the header first** — if the change +isn't allowed by the contract, the right move is a PR against the central +reusable, not a local edit. + +> **Why pin to `@v1`?** Stubs reference reusables by tag, not `@main`, so a +> bad commit on the central repo's `main` branch cannot break every +> downstream repo simultaneously. The `v1` tag is bumped deliberately when +> a backward-compatible release is ready; breaking changes will publish a +> `v2` tag that downstream repos opt into explicitly. + +### Available templates + +| Template | Tier | Purpose | +|----------|------|---------| +| [`agent-shield.yml`](workflows/agent-shield.yml) | 1 | Deep agent-config security scan via `ecc-agentshield` | +| [`claude.yml`](workflows/claude.yml) | 1 | Thin caller delegating to the org-level reusable Claude Code workflow | +| [`dependabot-automerge.yml`](workflows/dependabot-automerge.yml) | 1 | Auto-approve and squash-merge eligible Dependabot PRs | +| [`dependabot-rebase.yml`](workflows/dependabot-rebase.yml) | 1 | Rebase Dependabot PRs on demand | +| [`dependency-audit.yml`](workflows/dependency-audit.yml) | 1 | Multi-ecosystem audit (npm, pnpm, gomod, cargo, pip) | +| [`feature-ideation.yml`](workflows/feature-ideation.yml) | 1 | BMAD Method ideation pipeline (BMAD-enabled repos only) | **Adapt only when the template genuinely requires repo-specific content** (e.g., a project name in a comment, a different cron schedule for a known reason). Anything diff --git a/standards/workflows/agent-shield.yml b/standards/workflows/agent-shield.yml index b48ef5c..8704981 100644 --- a/standards/workflows/agent-shield.yml +++ b/standards/workflows/agent-shield.yml @@ -30,4 +30,4 @@ permissions: jobs: agent-shield: - uses: petry-projects/.github/.github/workflows/agent-shield-reusable.yml@main + uses: petry-projects/.github/.github/workflows/agent-shield-reusable.yml@v1 diff --git a/standards/workflows/claude.yml b/standards/workflows/claude.yml index b3ecd91..3faf303 100644 --- a/standards/workflows/claude.yml +++ b/standards/workflows/claude.yml @@ -36,7 +36,7 @@ permissions: {} jobs: claude-code: - uses: petry-projects/.github/.github/workflows/claude-code-reusable.yml@main + uses: petry-projects/.github/.github/workflows/claude-code-reusable.yml@v1 secrets: inherit permissions: contents: write diff --git a/standards/workflows/dependabot-automerge.yml b/standards/workflows/dependabot-automerge.yml index de974cd..845c329 100644 --- a/standards/workflows/dependabot-automerge.yml +++ b/standards/workflows/dependabot-automerge.yml @@ -35,5 +35,5 @@ jobs: permissions: contents: read pull-requests: read - uses: petry-projects/.github/.github/workflows/dependabot-automerge-reusable.yml@main + uses: petry-projects/.github/.github/workflows/dependabot-automerge-reusable.yml@v1 secrets: inherit diff --git a/standards/workflows/dependabot-rebase.yml b/standards/workflows/dependabot-rebase.yml index 21ebe40..b58dbb1 100644 --- a/standards/workflows/dependabot-rebase.yml +++ b/standards/workflows/dependabot-rebase.yml @@ -39,5 +39,5 @@ jobs: permissions: contents: read pull-requests: read - uses: petry-projects/.github/.github/workflows/dependabot-rebase-reusable.yml@main + uses: petry-projects/.github/.github/workflows/dependabot-rebase-reusable.yml@v1 secrets: inherit diff --git a/standards/workflows/dependency-audit.yml b/standards/workflows/dependency-audit.yml index 8024aa2..f117377 100644 --- a/standards/workflows/dependency-audit.yml +++ b/standards/workflows/dependency-audit.yml @@ -30,4 +30,4 @@ permissions: jobs: dependency-audit: - uses: petry-projects/.github/.github/workflows/dependency-audit-reusable.yml@main + uses: petry-projects/.github/.github/workflows/dependency-audit-reusable.yml@v1 diff --git a/standards/workflows/feature-ideation.yml b/standards/workflows/feature-ideation.yml index fa7b5ba..4807fbc 100644 --- a/standards/workflows/feature-ideation.yml +++ b/standards/workflows/feature-ideation.yml @@ -1,3 +1,21 @@ +# ───────────────────────────────────────────────────────────────────────────── +# SOURCE OF TRUTH: petry-projects/.github/standards/workflows/feature-ideation.yml +# Standard: petry-projects/.github/standards/ci-standards.md#8-feature-ideation-feature-ideationyml--bmad-method-repos +# Reusable: petry-projects/.github/.github/workflows/feature-ideation-reusable.yml +# +# AGENTS — READ BEFORE EDITING: +# • This file is a THIN CALLER STUB. The 5-phase ideation pipeline, the +# Opus 4.6 model selection, the github_token override, and the +# ANTHROPIC_MODEL env var all live in the reusable workflow above. +# • You MAY change: the `project_context` value (the only required edit +# per repo), and optionally the cron schedule. +# • You MUST NOT change: trigger event shape, the `uses:` line, the +# job-level `permissions:` block, or the `secrets:` block — these are +# required for the reusable to work. +# • If you need different behaviour, open a PR against the reusable in +# the central repo. The change will propagate everywhere on next run. +# ───────────────────────────────────────────────────────────────────────────── +# # Feature Ideation workflow stub — for BMAD Method-enabled repos. # # This is a thin caller for the org-wide reusable workflow at @@ -57,7 +75,7 @@ jobs: pull-requests: read discussions: write id-token: write - uses: petry-projects/.github/.github/workflows/feature-ideation-reusable.yml@main + uses: petry-projects/.github/.github/workflows/feature-ideation-reusable.yml@v1 with: # === CUSTOMISE THIS PER REPO — the only required edit === # Replace this paragraph with a 3-5 sentence description of your project,