Github Actions

[H1][GITHUB-ACTIONS]

Dictum: Workflow generation and validation enforce security, performance, and supply chain integrity.

Generate and validate production-ready GitHub Actions workflows and custom actions.

Tasks:

1. Gather requirements — triggers, runners, dependencies, environments, security posture.
2. Read best-practices.md — security hardening, supply chain, performance, anti-patterns.
3. Read version-discovery.md — SHA resolution protocol, action index, permissions.
4. Read expressions-and-contexts.md — contexts, functions, injection prevention.
5. (advanced triggers) Read advanced-triggers.md — workflow_run, dispatch, ChatOps, merge queue.
6. (custom actions) Read custom-actions.md — composite, Docker, JavaScript action authoring.
7. Resolve action versions — git ls-remote, Context7 MCP, or WebSearch for latest SHA.
8. Generate — SHA-pinned actions, minimal permissions, concurrency, caching, timeouts, harden-runner.
9. Validate — Read validation references, run actionlint, apply 11 best practice checks.
10. Fix and re-validate until passing (max 3 iterations).

Scope:

• Workflow files (.github/workflows/*.yml).
• Custom actions — composite, Docker, JavaScript (.github/actions/*/action.yml).
• Reusable workflows (workflow_call).
• Supply chain — SLSA attestation, SBOM, Cosign signing.
• Monorepo CI — Nx affected detection, sparse checkout, pnpm workspace caching.

References:

[1][STANDARDS]

Dictum: Mandatory standards enforce baseline quality across all generated workflows.

Every generated workflow enforces defense-in-depth: supply chain integrity prevents compromised actions from executing, minimal permissions limit blast radius if a job is compromised, and harden-runner detects anomalous behavior at runtime. These layers are independent — failure of one leaves others intact.

[CRITICAL]:

• [ALWAYS] SHA-pin every uses: reference — mutable tags (@v1, @main) enable supply chain attacks. The tj-actions incident (CVE-2025-30066) compromised 23,000+ repos via tag retargeting.
• [ALWAYS] step-security/harden-runner as first step in every job — detected the tj-actions breach before any other tool.
• [ALWAYS] Top-level permissions: {} (deny-all default); grant minimal per-job permissions.
• [ALWAYS] timeout-minutes: on every job — prevents runaway billing on stuck workflows.

[IMPORTANT]:

• [ALWAYS] OIDC federation (id-token: write) for cloud auth — eliminates static credentials entirely.
• [ALWAYS] actions/create-github-app-token for cross-repo ops — scoped, 1-hour expiry, survives offboarding.
• [ALWAYS] >> $GITHUB_OUTPUT for step outputs; >> $GITHUB_STEP_SUMMARY for job summaries.
• [NEVER] Direct ${{ }} interpolation of untrusted input in run: blocks — route through env: indirection.

[REFERENCE] best-practices.md — Security checklist, supply chain controls, anti-patterns.

[2][TEMPLATES]

Dictum: Templates scaffold canonical workflow and action structure.

Templates use [PLACEHOLDER] syntax for generation-time substitution. SHA resolution happens at generation time via the discovery protocol — templates contain placeholder SHAs, not static pins.

[2.1][PLACEHOLDER_CONVENTION]

All templates use a unified [UPPER_SNAKE_CASE] placeholder convention:

[2.2][HARDEN_RUNNER_SCOPE]

harden-runner is included as the first step in every workflow job template (basic, reusable). Action templates (composite, Docker, JavaScript) do NOT include harden-runner — the calling workflow is responsible for adding it as the first step in the job that invokes the action. Actions are steps, not jobs.

[2.3][TEMPLATE_INDEX]

[REFERENCE] custom-actions.md — Action type selection, metadata, runtime deprecation.

[3][EXAMPLES]

Dictum: Examples demonstrate production patterns for common scenarios.

Each example demonstrates distinct patterns with minimal overlap. Load relevant examples before generation to match the target scenario.

[4][ACTION_DISCOVERY]

Dictum: Runtime version resolution prevents stale SHA pins and supply chain drift.

Static SHA catalogs decay — actions release frequently and stale pins miss security patches. Resolve versions at generation time. Never embed hardcoded SHAs in reference docs or templates.

Resolution protocol:

1. git ls-remote --tags https://github.com/{owner}/{repo} — verify tag exists.
2. gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object.sha' — resolve tag to full SHA.
3. Format: owner/repo@<40-char-SHA> # vX.Y.Z.

Fallback methods:

• Context7 MCP: resolve-library-id then get-library-docs for action documentation.
• WebSearch: "[owner/repo] [version] github action" for release notes.

[IMPORTANT]:

• [ALWAYS] Verify the tag exists before pinning — deleted tags return empty results.
• [ALWAYS] Include version comment suffix (# vX.Y.Z) — Dependabot/Renovate parse these for automated updates.
• [NEVER] Embed static SHAs in reference files — they decay within weeks.

[REFERENCE] version-discovery.md — Discovery protocol, SHA pinning format, common actions index, automated maintenance.

[5][VALIDATION]

Dictum: Three-stage pipeline and 11 best practice checks gate workflow quality.

Validation pipeline:

Best practice checks (11):

Error routing: Match error patterns to reference files — common_errors.md (syntax, expressions, deprecated), runners.md (labels, deprecations), supply_chain.md (SHA, OIDC, SBOM, harden-runner), modern_features.md (reusable workflows, concurrency, matrix, node runtime), act_usage.md (actionlint rules, act limitations).

Troubleshooting:

[VERIFY] Completion:

• Supply chain: Every uses: reference SHA-pinned with # vX.Y.Z comment suffix.
• Security: Top-level permissions: {}, per-job minimal grants, harden-runner first step.
• Injection: No direct ${{ github.event.* }} in run: blocks — all through env: indirection.
• Performance: Caching enabled, concurrency groups set, timeout-minutes: on every job.
• Structure: Descriptive name: on workflow/jobs/steps, lowercase-hyphen filenames.
• Outputs: >> $GITHUB_OUTPUT for data, >> $GITHUB_STEP_SUMMARY for summaries.
• Harden-runner: Workflow jobs include it; action templates note caller responsibility.
• All errors resolved with reference-backed fixes; warnings documented.

[REFERENCE] best-practices.md — Anti-patterns with specific remediations.