config / rules

---
description: GitHub Actions Workflows Instructions
globs: .github/workflows/**/*.yaml, .github/workflows/**/*.yml, .github/actions/**/action.yml
---

# GitHub Actions Workflows Instructions

## Scope

- Scope covers designing, updating, and validating GitHub Actions workflows and composite action definitions.

## Standards

### Key Ordering

Keep map keys in alphabetical order (A-Z) within each block (see ORD-01 in Guidelines for review wording):

| Scope                         | In-scope key maps                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------- |
| Workflow and job              | `env`, `outputs`, `permissions`, `secrets`, `with`                                |
| Reusable workflow declaration | `on.workflow_call.inputs`, `on.workflow_call.outputs`, `on.workflow_call.secrets` |
| Composite `action.yml`        | `inputs`, `outputs`; per-step `env`, `with`                                       |

Any `env`, `inputs`, `outputs`, `permissions`, `secrets`, or `with` map is in scope. Out of scope for alphabetical ordering: `jobs` map keys and `on` trigger keys (keep semantic order). `steps` are ordered lists, not key maps.

Enforced by the `github-actions-validation` ORD-01 step (map key order check, run before actionlint, ghalint, and zizmor); also apply during edits.

## Guidelines

### Best Practices (BP)
- BP-01 (SHOULD): Extract shared pipelines to reusable workflows/composites
- BP-02 (SHOULD): Declare job dependencies with needs
- BP-03 (SHOULD): Keep secrets at minimal env scope
- BP-04 (SHOULD): Explicit with: for security/cache/core action inputs

### Error Handling (ERR)
- ERR-01 (SHOULD): Limit continue-on-error to non-critical justified steps
- ERR-02 (SHOULD): Use if: failure()/always() for cleanup/notify uploads
- ERR-03 (SHOULD): Set timeout-minutes on jobs or long steps

### Global / Base (G)
- G-01 (SHOULD): Narrow on triggers by branch/path/event
- G-02 (SHOULD): Production jobs use environment + approval

### Ordering (ORD)
- ORD-01 (MUST): Alphabetize keys in env/inputs/outputs/permissions/secrets/with maps

### Performance (PERF)
- PERF-01 (SHOULD): Deterministic cache keys invalidated by dependency changes
- PERF-02 (SHOULD): Balance matrix/parallelism vs runner cost
- PERF-03 (SHOULD): Cancel redundant runs with concurrency (caller-owned for reusable)

### Security (SEC)
- SEC-01 (MUST): Reference secrets only via secrets.\*; never echo them
- SEC-02 (MUST): Restrict pull_request_target on fork PRs
- SEC-03 (SHOULD): Mask sensitive values in logs (::add-mask / setSecret)
- SEC-04 (SHOULD): Validate/sanitize env inputs before use
- SEC-05 (SHOULD): Public repos gate privileged steps on private/trusted context

### Tool Integration (TOOL)
- TOOL-01 (SHOULD): Wire reviewdog for PR inline lint feedback when applicable
- TOOL-02 (SHOULD): Upload coverage to Codecov with a clear fail policy
- TOOL-03 (SHOULD): Set artifact retention intentionally (not default forever)

### Anti-Patterns (AP)
- AP-01 (MUST): Echoing or logging secrets
- AP-02 (MUST): pull_request_target on untrusted fork PRs without guards
- AP-03 (SHOULD): Floating third-party action tags
- AP-04 (SHOULD): Overly broad workflow permissions
- AP-05 (SHOULD): Passing untrusted PR input directly to shell

### Code Modification Guidelines

- Keep map keys alphabetically ordered per ORD-01 in companion github-actions-workflow rules (stem `github-actions-workflow`).


## Testing and Validation

On-demand validation: see github-actions-validation skill SKILL.md.

## Security Guidelines

- Keep `permissions` at least privilege and avoid unnecessary `write` scopes.
- Reference secrets only via `${{ secrets.* }}` and never print them to logs.
- Prefer commit SHA pinning for third-party actions and document reasons for exceptions.