GitHub Actions
Standard Platform
GitHub Actions is the standard CI/CD platform and the default choice when the user has not specified a pipeline system. Tool-agnostic pipeline rules live in Pipeline.
Action Upgrade Checklist
When creating or modifying a GitHub Actions workflow:
- Check whether the actions being used have newer stable versions.
- Review the official README or documentation before upgrading.
- Check for breaking changes.
- Check whether required inputs, permissions, runtime versions, or behavior have changed.
- Prefer moving to the current supported version when migration is safe.
Never bump an action version without checking its release notes first. Major-version tags (@v4) pick up minor and patch releases automatically; use this checklist when crossing a major version boundary.
CI Layering
CI should use the same standardized project tooling as local development wherever practical.
Prefer:
GitHub Actions
-> mise
-> project task
-> pnpm / uv / prek / cocogitto / test tooling
rather than duplicating project logic directly inside workflow YAML.
mise is the entry point CI invokes; do not duplicate tool setup in workflow YAML. See mise.
Event scoping
- Group triggers in each workflow file by the checks they require. A project-validation
workflow runs on
push(default branch) andpull_request; rules that exist only for pull requests — for example, PR title rules — live in their own workflow triggered bypull_requestalone. - Never emulate that split with
if: github.event_name == 'pull_request'on a job inside a multi-trigger workflow: onpushruns the job reports skipped and the run reads as a partial failure. See Pipeline for the tool-agnostic rule. pull_requestdefaults toopened,synchronize, andreopened— the right set for validating code. Listtypes:only to go beyond the default: a workflow that validates PR metadata an edit can change (the title) must addedited, so retitled pull requests re-verify. Never list activity types that cannot change the outcome; every listed type is another trigger.- Merge gates treat a skipped required check as passing, so this rule is for
readable run lists. The real merge hazard is a required check whose workflow
does not run on
pull_requestor whose job is filtered out — it never reports and stayspendingforever. Ensure every required check always runs and reports.
Checkout Depth
actions/checkoutfetches a single commit by default. Keep that default: most jobs only need the tree they validate.- Set
fetch-depth: 0only in a job that reads history —cog check, changelog generation,git describe, diff-against-base logic. - When one responsibility needs full history and the rest do not, split it into its own job rather than deepening the shared checkout. History-reading work is its own responsibility under Pipeline anyway, and the split keeps the validation job's checkout shallow.
Naming and Readability
For the tool-agnostic principle, see Pipeline.
GitHub Actions specifics:
- Give the workflow a
namethat states what it does (CI,Release). Do not rely on the filename, and do not repeat a job name as the workflow name. - Give every job a readable
name. Job names surface as status checks in branch protection; a reader must be able to map a failed check to a responsibility (Validate,Validate PR title), not to a tool invocation. - Name every step with a short imperative phrase saying what it does or
verifies (
Install dependencies (pnpm),Check commit history (cog)). Arun:step withoutnamerenders as its raw command, and commands are not documentation. - One concern per workflow file. Split by trigger or audience when they diverge; prefer several small workflows over one growing file.
Hardening Defaults
Apply these to every workflow unless it has a stated reason not to:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
validate:
timeout-minutes: 15
- Least privilege: default
permissionstocontents: read; widen only in the job that needs more. - Set
timeout-minuteson every job so a hung job cannot burn runner minutes up to the platform default. - Use
concurrencywithcancel-in-progressso superseded runs on the same ref are cancelled instead of queuing. - Pass untrusted input (PR titles, branch names, issue text) into
run:scripts through environment variables, never via direct${{ }}interpolation — direct interpolation enables script injection. - Reference actions by the current major version tag from a trusted publisher
(
actions/checkout@v7,jdx/mise-action@v4). The tag keeps receiving fixes, runtime updates, and new features inside that major, and an upgrade stays a one-token diff a reviewer can read. - Prefer the tag over a full commit SHA. A SHA freezes the action at one revision: fixes never arrive, the workflow stops stating which version it runs, and every upgrade becomes a manual SHA lookup. Pin a SHA only under a stated immutable-build or supply-chain policy, and record the resolved version in a trailing comment. Never leave an action on a bare branch name or an unversioned tag.
- A floating major tag trusts the publisher: pair it with the least-privilege defaults above, and never expose secrets to a workflow that runs pull-request code.
- Never use
pull_request_targetto check out and run pull-request code; it executes the base workflow definition with repository secrets. Usepull_request.
Related
- Pipeline — tool-agnostic pipeline structure and naming rules.
- Quality Gates — run equivalent local checks with the same project configuration.
- Git Workflow — Conventional Commits validation in CI, including the squash-merge pull-request-title rule.