CI security¶
How the GitHub Actions workflows in .github/workflows are protected, what each security job checks, and what to do
when a change adds an action or a tool. The repository settings that back this page (rulesets, allowed actions,
environments) are in GitHub settings.
Trust model¶
| Workflow trigger | Who can start it | Token and secrets |
|---|---|---|
pull_request |
anyone with a fork; runs for outside contributors wait for a maintainer's approval | read-only token, no secrets |
push to main or release-*, schedule, workflow_dispatch |
maintainers (merged pull requests) | per job, see below |
push of a v* tag |
only the owner (tag ruleset, admin role bypass) | the publish jobs, which start only after a maintainer approves the release environment |
workflow_run (pages.yml only) |
a successful tag-push run of release |
runs the default branch, reads no artifact of the triggering run |
Rules every workflow follows:
permissions: {}at the top; each job asks for the scopes it needs. Only the jobs that publish, sign or attest getpackages: write,id-token: writeorattestations: write, and none of them runs on a pull request.- No
pull_request_target,issue_commentorissuestrigger, and no job checks out pull request code with a privileged token. - Every
actions/checkoutsetspersist-credentials: false. - Values a contributor controls (pull request title, branch, tag, inputs) reach shell scripts only through
env:, never as${{ }}insiderun:. - Every action is pinned to a full commit SHA with a
# vX.Y.Zcomment; every container image is pinned by digest; every binary the Makefile or a workflow downloads itself has its version and SHA-256 recorded in the repository (bao, actionlint and ocm per OS and architecture in the Makefile, which refuses a platform without a pin; helm-unittest, pinact and poutine in the workflowenv:), or is built withgo installat an exact version (the Go checksum database verifies it). The envtest control-plane binaries are fetched bysetup-envtest, which checks them against its release index, and cosign by the SHA-pinnedsigstore/cosign-installeraction. - Cosign signing is keyless (OIDC to Sigstore), so the repository holds no cosign key. The workflows read three
secrets, each from an environment: the release-please GitHub App key (
RELEASE_APP_PRIVATE_KEY,release-pleaseenvironment), and the GPG chart signing key and its passphrase (HELM_SIGNING_KEY,HELM_SIGNING_PASSPHRASE,releaseenvironment), which only the step that packages the chart reads (chart signing key). - GitHub-hosted runners only. No AI agent runs in CI.
Security jobs¶
| Job (workflow) | Checks | Blocks the merge |
|---|---|---|
actionlint (workflows.yml) |
workflow syntax, expressions and shellcheck on run:; shellcheck on hack/release/*.sh, hack/github/*.sh and hack/docs/*.sh |
yes |
zizmor (workflows.yml) |
template injection, token permissions, dangerous triggers, cache poisoning, unpinned actions; uploads the full audit to code scanning | yes, on medium or higher |
pinact (workflows.yml) |
every uses: is a full SHA, its version comment resolves to that SHA upstream (no impostor commits from forks), and the release is at least 7 days old |
yes |
poutine (workflows.yml) |
untrusted checkout plus execution, injection, known-vulnerable actions, self-hosted runners on pull requests | yes |
analyze (go), analyze (actions) (codeql.yml) |
CodeQL for the Go code and for the workflows | yes, high alerts |
gitleaks (secret-scan.yml) |
secrets in the new commits; the weekly run rescans the history | yes |
osv-scanner (vulnerabilities.yml), govulncheck (ci.yml) |
known vulnerabilities in dependencies | yes |
dependency-review (dependency-review.yml) |
new dependencies with high-severity advisories or a denied licence | yes |
scorecard (scorecard.yml) |
OpenSSF Scorecard of the repository settings and workflows | no, reported to code scanning |
Accepted findings are suppressed one by one with a reason: .github/zizmor.yml or a # zizmor: ignore[...] comment on
the line, and .github/poutine.yml. Both files are owned by the maintainers (.github/CODEOWNERS).
Adding an action or a tool¶
- Prefer a
run:step withgh,curlor a tool the runner already has over a new third-party action. - Pick a release that is at least 7 days old and pin the full commit SHA with the exact version as a comment. Resolve
the SHA from the tag yourself (
git ls-remote https://github.com/<owner>/<repo> refs/tags/<version>) or runpinact runlocally, which reads.github/pinact.yaml. - Read the action's
action.ymlat that commit: nesteduses:must be SHA-pinned too, and inputs that pick a tool version must not default tolatest(set them, as the workflows do forcosign-release). - Give the job only the permissions the action documents, and keep secrets in the step that needs them.
- Add a third-party action to the allowed-actions list in
hack/github/apply-settings.shand GitHub settings, including any action it calls. - For a binary, record the version and SHA-256 in the step's
env:with a# renovate:comment, like the pinact and poutine installs inworkflows.yml; for an image, pintag@sha256:digest. Renovate then proposes updates after the same 7-day wait. - If you add, rename or remove a job that should block merges, update the required-check list in both
hack/github/apply-settings.shand GitHub settings.
Not adopted¶
- Workflow lockfiles (
.github/workflows/actions.lock): a GitHub Enterprise Cloud feature, not available to this repository. They also do not cover reusable workflows or images; SHA pins plus thepinactcheck do. - harden-runner egress blocking: a block list can only be written from an audit run of each job, and the agent
is downloaded at run time and reports to a third party. Adding it to the signing jobs would add code with access to
the OIDC token. The release jobs instead pull only digest-pinned images and checksum-verified tools, hold no
long-lived secret except the GPG chart signing key in the chart job, and wait for a maintainer's approval in the
releaseenvironment.