WorkingDirectory icon
Commands icon
Docker icon
Clone icon
Process icon
If icon
Comment icon
Switch icon
Fail icon
AllowFailure icon
Log icon
Webhook icon

Block new GitHub Actions workflow security findings before a change is merged

Stop risky GitHub Actions changes before merge. Kestra scans base and head workflows offline with zizmor and blocks only newly introduced findings.

Categories
Infrastructure

A pre-merge security gate for GitHub Actions. It answers one question before a change to a repository's CI is merged: does this change introduce a new workflow security problem?

GitHub Actions workflows run with repository tokens and secrets, so a single unsafe line (an untrusted pull request title expanded into a shell script, permissions: write-all, a third-party action pinned to a moving tag, a pull_request_target workflow that checks out the contributor's code) can hand an attacker the repository. This blueprint scans every workflow and composite action at the change's base and head commits with zizmor, compares the two, and blocks only the findings the change introduces. Findings that already existed are reported without blocking, so the gate can be adopted on a repository with history.

It complements repository posture tools such as OpenSSF Scorecard: instead of scoring a default branch through the GitHub API, it checks one proposed change, offline, finding by finding, before it lands. Unlike the scheduled, organisation-wide github-actions-hardening-sweep blueprint, it is a pre-merge gate that compares individual findings between exact base and candidate commits, blocks on qualifying newly introduced findings, and treats incomplete scans as inconclusive.

How it works

  1. fetch_tools downloads the zizmor 1.30.1 wheel for the worker's platform from PyPI with pip download --require-hashes --only-binary=:all:, against pinned SHA-256 hashes for the Linux x86_64 and aarch64 wheels. It runs before anything is cloned, so the only container with network access never sees repository content. A slow or stalled download is retried (up to three attempts) instead of failing the gate.
  2. clone_base and clone_candidate (io.kestra.plugin.git.Clone) check out the two exact commits, without submodules.
  3. verify runs on the Kestra worker and first drops every environment variable it does not need. It checks that each checkout is the requested commit, records workflow files and action manifests that are symbolic links, deletes every symbolic link so no container can follow one out of the clone, and removes the .git folders.
  4. scan runs in one container with networkMode: none, 2 CPUs, 1 GB of memory and no secrets. It installs zizmor offline from the hash-checked wheel and scans each workflow file (.github/workflows/*.yml, *.yaml) and each composite action manifest (action.yml, action.yaml) of both commits separately, as the unprivileged nobody user with an empty environment, using --offline --no-config --no-ignores --strict-collection --persona=pedantic --format json-v1. Findings are fingerprinted without line numbers, compared, and written to report.json together with the pull request comment.
  5. pr_comment (io.kestra.plugin.github.issues.Comment) posts the verdict when pr_number is set. updateTag keeps one comment per pull request, updated on every run.
  6. verdict (Switch) fails the execution on BLOCK and ends INCONCLUSIVE runs in WARNING, so a pipeline waiting on the gate can tell them apart.

Findings

zizmor's offline audits cover, among others, template injection of untrusted context into scripts, excessive or undocumented GITHUB_TOKEN permissions, dangerous triggers such as pull_request_target and workflow_run, actions and container images not pinned to a commit or digest, credential persistence through actions/checkout, cache poisoning, GITHUB_ENV injection, unsafe secrets: inherit, self-hosted runners and typosquatted actions. See the audit list.

  • A finding is qualifying when its severity is at least min_severity and its confidence is at least min_confidence (default: medium and medium). The pedantic persona is used so nothing is hidden; the thresholds decide what matters.
  • A finding is new when the candidate has more findings with its fingerprint than the base. The fingerprint is the audit, the file, the flagged source text, zizmor's annotation, severity and confidence, without the line number: a finding that only moved (lines added above it) is not new, while one whose severity or confidence went up is.
  • A finding in a file whose base version could not be fully scanned (a parse error, a limit, a symbolic link) is undecided: it is listed in the report but never counted as new or existing, and the verdict is INCONCLUSIVE unless something else is certainly new.
  • Each file is scanned on its own with --strict-collection. Scanning a whole directory would silently skip a file zizmor cannot parse; per file, every failure is visible.
  • The repository's own zizmor.yml and inline # zizmor: ignore[...] comments are ignored (--no-config --no-ignores), so a change cannot silence the findings it introduces.

Verdicts

Verdict Execution state Reason codes When
BLOCK FAILED NEW_FINDINGS (plus any incomplete-scan code below) At least one new qualifying finding. A finding that is certain is never hidden by another file failing to scan.
INCONCLUSIVE WARNING WORKFLOW_UNPARSEABLE, SCANNER_ERROR, SCAN_TIMEOUT, LIMIT_EXCEEDED, UNSUPPORTED_SYMLINK Something could not be scanned and no new qualifying finding was found. An incomplete scan is never PASS.
WARN SUCCESS EXISTING_FINDINGS Qualifying findings exist in the candidate, but all of them were already in the base.
PASS SUCCESS none, or NO_WORKFLOW_FILES Every file was scanned and there is no qualifying finding. NO_WORKFLOW_FILES says the candidate has no workflow or action file at all.

Limits per commit: 200 files, 1 MiB per file, 60 seconds per file and 480 seconds in total. Anything over a limit is reported as not analysed, never as clean, and a file that does not finish in time is SCAN_TIMEOUT. Typical workflow files scan in well under a second.

Inputs

Name Type Default Description
repo_url STRING demo repository Public GitHub repository, https://github.com/<owner>/<repo>. No other host, scheme, port, credentials or query.
base_commit STRING demo commit Full 40-character SHA the change is compared against, usually the pull request's base.
candidate_commit STRING demo commit Full 40-character SHA of the change, usually the pull request's head.
min_severity SELECT medium informational, low, medium or high.
min_confidence SELECT medium low, medium or high.
pr_number INT none Optional. When set, the verdict is posted on that pull request of the same repository.

The defaults compare two commits of a small public demo repository where the candidate only adds comment lines above two existing findings: the result is WARN (both findings are recognised as existing, not new), and nothing is written to GitHub.

Outputs

  • verdict: PASS, WARN, BLOCK or INCONCLUSIVE.
  • reason_codes: the codes behind the verdict, for example ["NEW_FINDINGS"].
  • new_findings: number of new qualifying findings.
  • report: report.json (schema kestra-github-actions-workflow-security-gate/1.0) with the commits, the policy, every scanned file and its status, new, existing and fixed qualifying findings (audit, severity, confidence, file, line, zizmor's annotation, the flagged source excerpt, documentation link and fingerprint), counts of findings below the thresholds, and everything that could not be analysed. Lists are sorted and the file contains no timestamps or execution IDs, so the same inputs produce a byte-identical report.

What you get

  • A clear, per-change verdict for workflow edits instead of a repository-wide score.
  • Adoption without a cleanup sprint: existing findings warn, new ones block.
  • Evidence a reviewer can act on: file, line, audit and documentation link for every finding, in report.json and in one pull request comment that stays up to date.
  • Honest failure semantics: a file that cannot be parsed, a scanner error, a timeout or a symbolic link is reported as not analysed, never as clean.

Who it's for

  • Platform and DevSecOps teams that review changes to CI before they reach the default branch.
  • Open source maintainers who accept workflow changes from contributors.
  • Security teams that need an auditable record of which CI changes were checked and why they passed.

Why orchestrate this with Kestra

A scanner on its own reports findings; a gate needs exact commits, a baseline comparison, isolation from the code it reads, retries and timeouts, a durable report and a decision other systems can wait on. Kestra keeps the networked download, the untrusted checkouts and the offline scan in separate tasks with their own limits, records every run with its inputs and report.json, exposes the verdict as an execution state for CI, and posts one up-to-date pull request comment.

Prerequisites

  • A Kestra worker that can run Docker containers, with outbound access to github.com and pypi.org / files.pythonhosted.org. The blueprint was tested on Linux x86_64; the aarch64 wheel is pinned too but has not been exercised.

Secrets

  • GITHUB_TOKEN: only when pr_number is set. A fine-grained token for the repository with Pull requests: read and write (or Issues: read and write). It is used by the comment task only and never reaches the scanner.
  • WORKFLOW_SECURITY_GATE_WEBHOOK_KEY: random key that forms the webhook URL, only if you use the webhook.

Quick start

  1. Run the flow with the defaults to see a WARN. The defaults use kestra-github-actions-security-gate-demo, a repository of synthetic workflows (GitHub Actions is disabled on it) whose README lists every commit. Keep repo_url and try these pairs:

    base_commit candidate_commit Result
    e28ccb0d2447f900e47cbf53899e006dc3f60b05 cc9759b83b995deebb768e6eadf8b1609f478f0e (comment lines added above two existing findings) WARN: EXISTING_FINDINGS (the defaults)
    7239b08f60ff7618aa1a0ca44595c89cb87a8369 (no workflows) 8fa1d8e1c6041248563513a84d07bd5889e2e82c (hardened CI workflow) PASS
    8fa1d8e1c6041248563513a84d07bd5889e2e82c 43f64722bacb90b8fa1c65bf99522474f2b50a48 (adds a third-party action pinned to a tag) BLOCK: NEW_FINDINGS (unpinned-uses)
    43f64722bacb90b8fa1c65bf99522474f2b50a48 e28ccb0d2447f900e47cbf53899e006dc3f60b05 (adds an issue workflow that expands the issue title into a script) BLOCK: NEW_FINDINGS (template-injection)
    8fa1d8e1c6041248563513a84d07bd5889e2e82c 893ceea45dc2717c8614a0f8ed9a9f3ac9912b1b (adds a workflow that is not valid YAML) INCONCLUSIVE: WORKFLOW_UNPARSEABLE
  2. Point the inputs at your own repository and the base and head commits of a pull request.

  3. To gate pull requests, call the webhook from CI and pass pr_number:

curl -fsS -X POST -H 'Content-Type: application/json' \
  -d "{\"repo_url\": \"https://github.com/${GITHUB_REPOSITORY}\", \"base_commit\": \"${BASE_SHA}\", \"candidate_commit\": \"${HEAD_SHA}\", \"pr_number\": ${PR_NUMBER}}" \
  "https://<your-kestra-host>/api/v1/<tenant>/executions/webhook/company.team/github-actions-workflow-security-gate/${WORKFLOW_SECURITY_GATE_WEBHOOK_KEY}"

Webhook values go through the same validators as a manual run: an invalid request gets HTTP 422 and no execution. min_severity and min_confidence default to medium when omitted.

Security model

  • Repository content is untrusted and only ever read as text. zizmor parses YAML; it never runs workflow steps, scripts, build files or package managers, and nothing from the repository is installed.
  • The scanner runs offline (--offline and networkMode: none), as nobody, with an empty environment, so it cannot use a GITHUB_TOKEN and cannot reach the network. GITHUB_TOKEN is referenced only by the comment task.
  • Symbolic links are deleted on the worker before any container starts, and inputs are collected as regular files only, so a link cannot pull a file from outside the clone into the scan. A workflow file or action manifest that is a link is reported as UNSUPPORTED_SYMLINK.
  • Repository-controlled zizmor configuration and ignore comments are disabled.
  • Text from the repository (file names, annotations) is placed in code spans in the pull request comment, so it cannot inject markup or mentions. The flagged source excerpt is kept in report.json only.

Limitations

  • Offline mode skips zizmor's four online audits (impostor-commit, known-vulnerable-actions, ref-confusion, stale-action-refs), which need the GitHub API.
  • Only .github/workflows and composite action manifests are scanned; Dependabot and pre-commit configuration are not.
  • A renamed workflow file counts as removed and added, so its findings are reported as new.
  • Both commits are cloned in full (without submodules). Very large repositories take longer and are bounded only by the 10-minute clone timeout.
  • zizmor is a static analyser of workflow definitions: it does not see what scripts, actions or containers do at run time, and its findings follow its own rules and personas.
  • The per-file and total time limits and the download retry were checked with shortened limits and a test flow; a scan reaching the real limits and a retry during a genuinely slow PyPI download have not been exercised.

How to extend

  • Raise or lower min_severity and min_confidence, or run it on a schedule against the default branch with the same commit as base and candidate to get an inventory of existing findings.
  • Send BLOCK results to Slack or open an issue from report.json by adding tasks after verdict.
  • Add a gate-side allowlist of accepted fingerprints, owned by the platform team rather than by the repository being scanned.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.