github-actions

GitHub Actions

Treat a workflow as production code with credentials. Anchor security on the trust boundary, performance on the critical path, and correctness on the execution graph. Preserve behavior deliberately and prove the changed path.

Process

Select every requested mode first:

• Audit: inspect and report without edits when selected alone.
• Modify: diagnose and change an existing workflow or Dependabot configuration.
• Create: add a new workflow, reusable workflow, or Dependabot configuration.

Modes can combine. For an audit-and-fix request, audit first, modify the authorized findings, and report both corrected and outstanding findings.

After mode selection, use Dependabot and dependency automation as the specialized process for a Dependabot-only task. Apply the workflow execution-graph process below only to repository workflows triggered by Dependabot or generated for dependency submission.

1. Map the affected pipeline

For an existing workflow, traverse every reachable local action and reusable workflow. Deduplicate source reads by immutable identity, but analyze every call edge with its caller's ref, inputs, secrets, permission ceiling, conditions, environment, and runner. When a reusable contract can change, find every affected caller. For creation, map repository conventions and candidate components implied by the requested behavior.

For every affected execution branch, identify:

• events, actors, refs, fork and Dependabot behavior, approval and hold gates, default-branch semantics, and governing Actions policies
• code, expressions, artifacts, caches, inputs, and network data each job consumes
• token permissions, secrets, OIDC claims, environments, and runner access each job receives
• the job and step graph, including needs, conditions, outputs, matrices, background lifecycles, concurrency, and cancellation
• package manager, lockfiles, scripts, runtime versions, runner labels, and existing CI conventions
• required checks, deployment ordering, release guarantees, and the behavior users depend on
• for performance or cost work, satisfy the target and baseline gate; for cost, also collect and attribute evidence

Load the anchored reference as soon as its observed context matches:

Observed context	Load
An entrant can influence a job with authority	Trust-boundary map and token permissions
A privileged or default-branch event handles contributor influence	Privileged events
An external dependency, checkout, local ./ or $/ action, or workflow policy matters	Dependencies and workflow governance
Secrets, OIDC, environments, or cloud credentials matter	Secrets, OIDC, and environments
Artifacts or caches cross jobs, workflows, refs, or trust levels, or Actions retention settings change	Artifact promotion or cache-poisoning chain
A self-hosted runner or Actions policy matters	Runners and network reach or platform execution protections
A run is held, awaits approval, or is blocked before a job starts	Approval gates and held runs and, for policy denials, platform execution protections
A run: block is created, changed, or reviewed	Shell semantics, expression boundary, failure handling, and workflow data
A run: block writes a transient file	Runner-owned temporary storage
GitHub API, gh, or github-script is used	Choose the narrowest API, then its matching interface section
workflow_dispatch is sent through an API or its run must be tracked	Workflow dispatch
Secret-scanning custom patterns are automated	Secret-scanning custom patterns
Dependabot configuration, alerts, dependency graphs, dependency submission, private registries, or Dependabot pull-request behavior matters	Dependabot and dependency automation
Outputs, environment writes, or summaries are used	Workflow channels
Events, filters, expressions, failure, cancellation, or timeouts matter	Events and refs, expressions, or failure
Concurrency, matrices, or reusable contracts matter	Concurrency, matrices, or reusable workflows
Latency, cost, parallelism, setup, runners, caches, or artifacts matter	Name the target and baseline, then the matching performance section
Actions metrics, billing reports, dashboards, or GitHub-generated workflows matter	Collect and attribute evidence

Complete when: every requested mode is selected; every affected workflow, caller, reachable local dependency, and distinct call context is accounted for; every entrant, execution edge, capability, and behavioral contract is mapped; every Dependabot task satisfies its dependency-surface gate; and performance work satisfies its linked target-and-baseline gate.

2. Shape the safe execution graph

Compare the mapped graph with the target below for every selected mode. In audit-only mode, record evidence-backed divergences without editing. For modification or creation, shape this target; when combined with audit, retain the divergences as evidence for the changes:

• Choose the least-privileged event that supplies the required context.
• Establish a deny-by-default token baseline and grant each job only its required permissions.
• Constrain untrusted values crossing into privileged operations so they cannot control execution, authority selection, destination, or side-effect scope.
• Add only data, isolation, or lifecycle edges; start independent work as soon as its dependencies allow.
• Make required-check, failure, retry, timeout, cancellation, and concurrency semantics explicit.
• Give deployments and releases protected environments, immutable inputs, and deliberate queueing.
• Use locked dependency installs and explicit shell semantics where scripts depend on them.
• Make every external dependency immutable through the verification procedure below.
• Shape a performance change against the linked target and baseline, accounting for startup, compute, cache, and artifact-transfer work.

Complete when: every selected audit has compared every mapped edge with every loaded rule; every selected modification or creation has a target graph where capabilities, trust crossings, ordering, required outcomes, and deployment semantics are justified; and a performance design has an evidence-backed expected impact ready for proof.

3. Execute every selected mode

Audit

Record findings ordered by impact. In audit-only mode, return them without editing. When audit is combined with modification, mark each finding as corrected or outstanding in the final report. Each finding includes:

• severity and exact file:line
• triggering event, actor, or input
• concrete failure, privilege, or performance path
• smallest safe correction
• validation evidence or the exact evidence gap

A security finding needs a concrete path from untrusted influence to a capability. Label defense-in-depth and stylistic hardening separately. A performance finding needs a measured bottleneck or a clearly labeled model of the critical path. State explicitly when no findings remain.

Modify

Start from observed behavior. Trace each problem through its trigger, inputs, execution path, and result. Correct it at the source with the smallest cohesive change. Preserve package-manager, lockfile, runner, naming, and workflow conventions unless one causes the problem. Update every affected caller when a reusable-workflow contract changes.

Create

Build the smallest execution graph that satisfies the requested behavior. Reuse established local actions, reusable workflows, package commands, and naming instead of introducing a second convention. After drafting, remap the generated graph and load every newly matching reference.

When an external reference changes

Treat a new action, reusable workflow, container image, or explicit upgrade as a dependency change:

1. Identify the intended release and read its release notes and migration guidance.

2. Resolve an action or reusable-workflow tag through its own repository's commit endpoint so annotated tags yield the commit SHA:

   repo='OWNER/REPOSITORY'
   tag='REVIEWED_RELEASE'
   gh api "repos/$repo/commits/$tag" --jq .sha
   gh api "repos/$repo/releases/tags/$tag" --jq '{tag_name,html_url,body}'
   

3. Verify the SHA belongs to that repository; inspect source behavior, action metadata, runtime and runner floors, permissions, and input handling relevant to this workflow. On GitHub.com, JavaScript actions run only on Node 24 and the Node 20 opt-out is gone: replace a release that still declares runs.using: node20 with a Node 24-compatible one, and treat self-hosted runners on macOS 13.4 or earlier or on ARM32 as unsupported.

4. Pin container images by digest. Outside a workflow onboarded to a lockfile, set uses: to the reviewed SHA; wherever uses: holds a SHA, update it and its human-readable release comment together.

5. When the repository tracks .github/workflows/actions.lock, check whether the affected workflow appears in its workflows section. For an onboarded workflow, change uses: in the repository's existing form and regenerate its entries with gh actions-lock <workflow-path> instead of editing the lockfile; a run without paths also prunes entries and rewrites every workflow it scans. Onboard a new workflow the same way. A normal run keeps existing entries, so a branch or partial-version pin such as @main or @v4 advances only with --relock. If a locked commit is no longer reachable upstream, --relock reports an error and writes nothing; verify the upstream history before adding --accept-moved. Keep the tool's uses: rewrites: it can replace a floating tag with the exact release it locked and convert a resolvable ./ action to $/, which changes the code's source (see local action references). Before onboarding, fix any ./ action reference the run would keep (migrate it to $/, correct its path, or remove the step), or pass only the other workflow paths. The documentation says such a workflow is skipped, but check the workflows section afterwards: an empty entry onboards a workflow with no dependencies, and GitHub then rejects its remote actions. Until a workflow is onboarded with its entries, step 4 applies to it. In an onboarded workflow a remaining ./ action reference is a blocking error: the run writes nothing, so migrate it to $/, fix its path, or remove the step before regenerating. Review the full diff, confirm each changed commit is the reviewed SHA, investigate a changed owner_id or repo_id as a possible transfer or substitution before accepting it, then run gh actions-lock --verify.

An explicit upgrade authorizes the compatible upgrades it names. During unrelated work, preserve existing versions unless one blocks the requested behavior or has a relevant security defect.

Complete when every selected mode gate passes:

• Audit: every mapped edge and loaded rule is assessed, producing evidence-backed findings or an explicit no-findings result.
• Modify: every requested behavior is corrected at its source, affected callers are updated, and the resulting graph is remapped.
• Create: every requested behavior is present in the smallest conforming graph, and the generated graph is remapped.
• Dependency change: every changed reference and lockfile entry resolves to the reviewed immutable object, and its runtime contract remains compatible.
• Dependabot: every affected dependency surface and automation plane satisfies the Dependabot criterion.

4. Prove the workflow

1. Run the repository's configured workflow lint command; otherwise run actionlint against every affected workflow. A linter can lag current syntax: actionlint 1.7.12 rejects valid $/ references, parallel, background, wait, wait-all, cancel, queue: max, cache-mode, the vulnerability-alerts permission, job.workflow_* contexts, and new runner labels such as ubuntu-26.04. Confirm each such error against current GitHub Docs, keep the valid syntax, and report the linter version and gap; fix every other finding.
2. For a modified local action, validate its metadata with the configured schema tool (on GitHub.com, a JavaScript action declares runs.using: node24) and exercise its declared inputs, outputs, entrypoint, post behavior, and representative caller.
3. Run each configured Actions security analyzer and reconcile its output with the trust-boundary map; static analysis supplements path tracing.
4. Run safe underlying commands from changed run: steps with the repository's locked dependency state. Use a documented dry-run for release or deployment commands.
5. For performance changes, satisfy the performance criterion. Report inaccessible remote execution as the exact measurement gap.
6. For combined Dependabot and workflow changes, also satisfy the Dependabot validation and criterion.
7. Recheck the complete affected graph: event, approval, hold, and policy semantics; permissions, secrets, OIDC, environments, and runners; dependency pins; local and reusable contracts; outputs, matrices, caches, artifacts, concurrency, background barriers, and needs.
8. Report exact commands and outcomes. Name an unavailable runner, credential, service, policy, or tool as a verification gap.

Complete when: every affected workflow, modified action manifest, and modified Dependabot configuration has passing applicable validation or an exact tool blocker; every changed behavior has direct execution evidence or an exact external blocker; every security conclusion names the traced path; and every optimization satisfies the linked performance criterion.