GitHub Actions Workflow Review Checklist: Secrets, Permissions, Caching, and Reliable Deployments

Overview

Review a workflow as both executable code and a change to your delivery system. The YAML syntax is only one part of the review. You also need to understand who can trigger the workflow, which code runs with elevated access, what data crosses job boundaries, and what happens when a job fails or is retried.

Start by identifying the workflow's purpose: validation, packaging, scheduled maintenance, preview deployment, production deployment, or another task. A workflow with a narrow purpose is easier to secure and maintain than one that combines unrelated responsibilities. Record the expected triggers, required inputs, outputs, permissions, environments, and deployment targets before reviewing individual steps.

Use this checklist alongside the rest of your delivery controls. For example, a container workflow may need the same image and Dockerfile checks described in the Dockerfile review checklist. Infrastructure changes should be reviewed with a comparable discipline, such as the checks in the Terraform plan review checklist.

Checklist by scenario

For every workflow

• Confirm the trigger scope. Check branches, paths, tags, schedules, manual inputs, and event types. Ask whether a workflow can run from an untrusted branch, pull request, fork, or generated file change.
• Define least-privilege permissions. Set the workflow or job permissions explicitly rather than relying on broad defaults. Grant write access only to the job that needs it, and keep validation jobs read-only where possible.
• Check the runner choice. Verify that the selected runner has the required operating system, tools, architecture, network access, and resource profile. Treat self-hosted runners as sensitive infrastructure and avoid allowing untrusted code to share them with privileged jobs.
• Pin reusable actions deliberately. Review every third-party action, its owner, requested permissions, and maintenance process. Pinning to an immutable reference can make changes easier to audit than a moving branch or loosely specified tag.
• Make the execution order understandable. Use descriptive job and step names, explicit dependencies, and clear outputs. A reviewer should be able to tell which checks are mandatory and which are informational.
• Keep logs useful but safe. Do not print tokens, credentials, private configuration, or sensitive request data. Be cautious when enabling shell tracing or dumping environment variables during troubleshooting.

For pull request and branch validation

• Ensure the workflow tests the code that is actually being reviewed, not an unintended default branch or mutable reference.
• Separate untrusted pull request code from jobs that can access deployment credentials or write to protected resources.
• Use required checks consistently. Renaming a job or changing its condition can leave branch protection rules pointing at the wrong status.
• Check conditional expressions for skipped jobs. A skipped job may be acceptable, but it should not accidentally bypass a required security or test gate.
• Make failures actionable by preserving test reports, compiler output, and relevant logs without exposing secrets.

For build, test, and matrix workflows

• Keep the matrix intentional. List supported language versions, operating systems, databases, or architectures explicitly. Exclude combinations that are known to be invalid instead of allowing confusing failures.
• Identify the required result. Decide whether every matrix combination must pass or whether one representative job is the release gate. Document exceptions rather than hiding them in conditions.
• Use caching for repeatable inputs. Cache package-manager data or other safe, reconstructable dependencies using keys that include the relevant lockfile, platform, and runtime dimensions. A cache should improve speed, not become a source of correctness.
• Validate cache fallback behavior. A cache miss should trigger a clean installation. Do not assume that a partial or stale cache contains everything a build requires.
• Make artifact boundaries clear. Name artifacts by purpose and context, upload only the files needed by later jobs, and define how artifacts are consumed, retained, and verified.

For deployment workflows

• Separate build, verification, and deployment jobs so that production access is not available to every step.
• Use protected environments or an equivalent approval control for sensitive targets. Confirm that the deployment job references the intended environment and that its secrets are not exposed to earlier jobs.
• Check the deployment identity and scope. Prefer a narrowly scoped identity for the target service, account, cluster, or registry.
• Define concurrency behavior. Decide whether a newer deployment should cancel an older pending run, queue behind it, or be blocked while another deployment is active.
• Specify rollback or recovery expectations. The workflow should make it possible to identify the deployed revision and determine what operators do after a failed rollout.
• Verify approvals and status checks at the point where production access is used, not only in an earlier job that can be bypassed by a condition.

Annotated baseline pattern

The following pattern is intentionally conservative. Adapt names, permissions, runners, and deployment details to your repository rather than copying it as a complete production solution.

name: Validate and deploy

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<reviewed-reference>
      - name: Install dependencies
        run: ./scripts/ci-install.sh
      - name: Run tests
        run: ./scripts/ci-test.sh

  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: test
    environment: production
    permissions:
      contents: read
      deployments: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<reviewed-reference>
      - name: Deploy
        run: ./scripts/deploy.sh

The important review points are the explicit read permission at workflow scope, narrower job-level permissions, a dependency between testing and deployment, a deployment-only condition, a named environment, and a concurrency policy. The action references and scripts still require separate review.

What to double-check

Secrets and credentials

List every secret, variable, token, and external credential used by the workflow. For each one, record which job needs it, whether it is available to pull requests or forks, and whether it can be replaced with short-lived or workload-specific access. Never use a secret merely because it is convenient when a narrower credential is available.

Inspect shell commands for accidental disclosure through command arguments, error messages, generated files, and uploaded artifacts. Also review scripts called by the workflow; a secure YAML file cannot compensate for a script that echoes credentials or trusts unvalidated input.

Expressions and untrusted input

Review values derived from branch names, pull request titles, issue text, commit messages, workflow inputs, and external events before placing them in shell commands. Treat these values as data, pass them through safe environment variables where appropriate, and avoid constructing commands by concatenating untrusted text.

Dependencies and action changes

For each action and setup step, ask what code it executes, what permissions it receives, and how an upgrade is reviewed. Keep dependency installation reproducible with lockfiles or equivalent constraints. If caching is enabled, verify that the cache key changes when dependency definitions or relevant build settings change.

Failure and cancellation behavior

Read every if, continue-on-error, timeout, retry, and cancellation setting as a policy decision. A non-blocking security scan may be appropriate in an informational workflow but unsafe as the only check before deployment. Confirm that cleanup steps run when expected and that a cancelled or partially completed deployment leaves an understandable status.

Outputs, artifacts, and provenance

Check that job outputs are stable, minimal, and not derived from untrusted text without validation. Verify that artifacts cannot be confused across branches or runs. If a later job deploys an artifact, confirm that it receives the artifact produced by the reviewed commit rather than rebuilding different source code.

Common mistakes

• Using broad permissions everywhere. A workflow that only runs tests rarely needs write access to repository contents, releases, packages, or deployments.
• Giving deployment secrets to test jobs. Keep credentials in the smallest possible job and use environment controls for sensitive targets.
• Trusting mutable action references. A moving reference can change without an obvious workflow diff. Establish a review and update process for action references.
• Treating cache hits as proof of correctness. Caches are optimizations. Builds must remain correct after an empty cache, a changed lockfile, or a new runner.
• Allowing every matrix job to deploy. Matrix expansion belongs in compatibility testing unless there is a specific reason to deploy from multiple variants.
• Hiding failures with conditions. Complex conditions can make a workflow appear green while a meaningful job was skipped. Prefer simple gates and explain exceptional paths.
• Mixing build and release concerns. A single large job is difficult to review, retry, audit, and secure. Separate responsibilities around trust boundaries.
• Changing required check names casually. Coordinate workflow changes with repository rules so that a renamed or removed check does not weaken the merge gate.

For broader pipeline design decisions, compare the workflow with the principles in this CI/CD tools comparison. If the workflow validates API contracts or generated clients, the OpenAPI toolchain guide can help clarify where contract checks belong.

When to revisit

Run this review before merging every new workflow and whenever an existing workflow changes its triggers, permissions, action references, runner type, cache key, matrix, artifact handling, secret, environment, or deployment target. Repeat it when repository protection rules or organizational security requirements change.

Schedule a broader workflow review before seasonal planning cycles and at least whenever your team changes its release process. Recheck runner capabilities, action behavior, platform syntax, quotas, and billing assumptions against current documentation instead of treating this checklist as a substitute for provider guidance.

A practical review loop is:

1. Open the workflow and list its triggers, jobs, permissions, secrets, environments, artifacts, and external actions.
2. Trace the path from an untrusted change to each privileged operation.
3. Test cache-miss, failure, retry, cancellation, and approval scenarios.
4. Confirm that required checks still protect the intended merge and deployment gates.
5. Record unresolved risks, assign an owner, and link the review to the workflow change.

Keep this checklist with your repository or engineering handbook so it is used during code review rather than remembered only after a failed deployment. A small, repeatable review is one of the most dependable DevOps tools for keeping automation understandable, secure, and reliable as a team grows.