github-actions-conventions

name	github-actions-conventions
description	GitHub Actions / CI conventions (canonical quality/build/chart/release

GitHub Actions conventions

Apply these when the repo is hosted on GitHub.

YAML style (workflows and .github/ config)

• No leading --- document marker at the top of workflow or other .github/ config YAML files. Start directly with the first key.
• Write the trigger key as bare on:, never quoted "on":. (Modern parsers and actionlint handle the YAML truthiness of on fine.)
• Block style only, consistent with yaml-conventions.

Step naming

• Every step has a name: — mandatory for uses: steps, and expected on run: steps too. A nameless action step reads as a bare SHA in the UI.
• Step names start with a lowercase letter (not sentence-cased): name: set up the Rust toolchain, not name: Set up the Rust toolchain. Proper nouns inside the name keep their capitals (Rust, GHCR, GitHub).
• Keep step names static — never interpolate a ${{ }} expression into a name:. A conditional/templated label adds noise for no real benefit; pick one fixed name (name: build the image, not name: build${{ inputs.push && ' and push' || '' }}).

Pin actions by SHA

• Pin every uses: to a full commit SHA, with a trailing comment naming the tag it corresponds to — and that comment must track the latest release tag of the action:

  - uses: actions/checkout@<40-char-sha>  # v4.2.2
  

  A tag is mutable; a SHA is not. Resolve the SHA of the latest tag with git ls-remote --tags https://github.com/<owner>/<repo> '<tag>^{}'.
• Add .github/dependabot.yaml with the github-actions ecosystem so the pinned SHAs (and their tag comments) are bumped automatically.
• Never use a bare branch or tag ref (@v4, @main, @stable) in a committed workflow.

The canonical workflow set

Create exactly these workflows, conditioned on what the repo contains. Give each least-privilege permissions: (default contents: read; widen only in the job that needs it).

• quality — always. Runs pre-commit run --all-files and the test suite, on push to the default branch and on every pull request. Because the language: system hooks shell out to real binaries, the job must install every tool the hooks need (toolchain + helm, helm-docs, hadolint, actionlint, …) before running pre-commit. This is the single quality gate — do not scatter fmt/lint/test across ad-hoc workflows.
• build — when a Dockerfile exists. Builds the image, and pushes only when explicitly asked: triggered by workflow_dispatch (a push boolean input) or invoked via workflow_call with push: true. On a plain push/PR it builds without pushing (validation only). Expose push and version as workflow_call/workflow_dispatch inputs. Multi-arch Rust: always a static matrix over both architectures — amd64 on ubuntu-24.04 and arm64 on ubuntu-24.04-arm — each on its own native runner. Never QEMU-emulate a Rust build, and never drop an architecture from the matrix on PRs (validate both). When pushing, each arch job build/pushes by digest and a final manifest job assembles the multi-arch manifest (that job runs only when pushing). Derive image tags and labels with docker/metadata-action — labels on each per-arch build, tags in the manifest job (consumed from DOCKER_METADATA_OUTPUT_JSON by docker buildx imagetools create). Never hand-roll tag strings.
• chart — when a Helm chart exists. Publishes the chart as an OCI artifact to GHCR (helm push → oci://ghcr.io/<owner>/charts). The chart has its own release lifecycle, decoupled from the app: trigger it on a dedicated tag namespace chart-* (plus for manual publishes), never on PR (PR validation is inside ). Derive the chart version from the tag and pass it to ; leave to (the app image the chart targets evolves independently of the chart's own version). The workflow does publish the chart.

Path filters — don't trigger for nothing

• A workflow triggered on push/pull_request must carry a paths: (or paths-ignore:) filter so it only runs when files that actually affect it change. A multi-arch image build must not fire on a docs-only or chart-only change; scope it to its real inputs (e.g. src/**, Cargo.toml, Cargo.lock, Dockerfile, .dockerignore, and the workflow file itself).
• Exception — the quality workflow (pre-commit + tests) is never path-filtered. It is the universal gate and must run on every push and pull request, whatever changed.
• Tag-triggered workflows (chart on chart-*, release on v*) and workflow_dispatch / workflow_call take no paths — path filters do not apply to those events.

Concurrency — one run per workflow per ref

Every workflow carries a top-level concurrency: block keyed on the ref, so two runs of the same workflow never overlap on the same branch or tag:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

• cancel-in-progress: true, always — no exceptions, publishing workflows included. A run for a superseded commit is dead weight; kill it and free the runner. Do not reach for false on release/chart to protect a push mid-flight: registries are the place to make a partial publish safe (immutable tags, digest-addressed pushes, a re-run of the same tag), not the concurrency block. Never write cancel-in-progress: false, and never make it conditional on the event.
• In a reusable (workflow_call) workflow, hardcode the workflow name in the group instead of ${{ github.workflow }}. In a called run that expression resolves to the caller, so build would land in the same group as release and cancel the very job waiting on it. Write group: build-${{ github.ref }}.
• Key on github.ref, not github.head_ref — the latter is empty outside pull_request events and would collapse every push into one shared group.

Cache deliberately, and pragmatically

Cache what is expensive to recompute, not what is cheap to re-download. The crates.io / registry download is fast; restoring a large dependency cache can be slower than a clean fetch, and a stale cache is worse than none.

• Keep: the Docker layer cache, scoped per architecture (type=gha,scope=<arch>) so the two arch runners never clobber each other; and the compiled-dependency cache (cargo-chef in the Dockerfile, Swatinem/rust-cache for non-Docker Rust jobs) — these cache CPU work, not downloads.
• Skip: caches wrapped around a fast download just because you can. Measure before adding one.

Never:

• Never start a workflow file with ---, and never quote "on".
• Never use a bare branch/tag action ref — pin the SHA (with a tag comment) and let Dependabot bump it.
• Never push an image or publish a chart on a pull request; pushing happens only via workflow_dispatch or the release orchestration.
• Never cut a release by editing a version field — derive the version from the git tag at build time.
• Never QEMU-emulate a Rust multi-arch build when native runners exist, and never share one unscoped build cache across architectures.
• Never split the quality gate: pre-commit + tests live in the single quality workflow.
• Never ship a workflow without a concurrency: group, and never set cancel-in-progress to anything but true — not false, not an expression, not even on release/chart.