How do you prevent shell injection in GitHub Actions run steps?

Prevent it by treating every untrusted value as data, not shell code. Avoid interpolating pull request, branch, or issue content directly into run scripts, and prefer passing values through environment variables with careful quoting. Keep scripts minimal, validate inputs before use, and review any step that builds commands from workflow context or repository content.

Where shell injection appears in GitHub Actions

Shell injection in GitHub Actions usually shows up when a step turns workflow context, event payloads, or repository content into a command string. The danger is not the YAML itself, it is the shell evaluating characters such as semicolons, backticks, command substitution, or untrusted filenames as executable syntax. GitHub’s own guidance is strongest when you treat every value as untrusted until it has been validated and quoted.

The practical boundary is between data and code. If a step only passes a value to a tool as an argument, the shell has less opportunity to reinterpret it. If the step concatenates strings into one line and sends that line to GitHub and GitHub Actions Security Guide territory, the workflow is relying on quoting discipline that can fail under edge cases. That is why minimal scripts and explicit argument passing are safer than assembling commands from event text.

A useful rule is to assume that pull request titles, issue bodies, branch names, commit messages, and file paths can all carry hostile syntax. Even when the source is internal to the repository, a contributor or dependency compromise can turn ordinary metadata into an execution vector. The safer pattern is to normalise the value, store it in an environment variable, and pass it into the tool in a form the shell does not reparse.

Safer workflow patterns that reduce command parsing risk

The cleanest prevention strategy is to avoid building shell commands from workflow context in the first place. Prefer direct action inputs, fixed command templates, and purpose-built tooling over inline shell fragments. When a shell step is unavoidable, keep the script short, quote every expansion deliberately, and use input validation before the value reaches a sensitive branch, file path, or option flag.

Where the workflow needs to process repository-controlled text, resist the temptation to “just echo it” into another command. Use environment variables for transport, not as a substitute for validation, and make sure the downstream command consumes the value as data. This is especially important when the step runs on a privileged runner, has access to secrets, or can publish artifacts, because a single injection flaw can become credential theft or release tampering.

Review steps that construct commands from GitHub context with extra care if they run on pull request events, use matrix values, or consume filenames generated by another job. Those are common places for hidden interpolation bugs. The strongest workflows either avoid shell composition entirely or constrain it to a very small, auditable surface.

For broader workflow hardening, the CI/CD Pipeline Identity Security Guide is the right companion when you are deciding how much privilege a job should have and how untrusted builds should be isolated. It helps frame shell safety as part of a larger pipeline trust problem, not a formatting problem.

What to test before you trust a workflow step

Testing should focus on whether an attacker can influence the final command line, not just whether the script “looks quoted”. A workflow is still risky if a value passes through several layers and only becomes dangerous at the last shell invocation. The most useful review question is simple: can any untrusted input alter the command structure, option parsing, or file path resolution?

For that reason, inspect three things during review: where the value comes from, how it is transported, and where the shell finally interprets it. If any of those stages allow command substitution, newline injection, globbing, or option injection, the step needs redesign. The goal is to ensure that the shell sees a fixed command with variable data, not a mutable command assembled from context.

When you need a reference point for workflow hardening and runner risk, the GitHub and GitHub Actions Security Guide and the OWASP Top 10 both reinforce the same operational instinct: trust boundaries matter, and injection flaws become severe when they sit close to privileged execution. For GitHub Actions, that usually means reviewing the step as if it were a small attack surface of its own.

Risk and Threat Considerations

Shell injection in CI is risky because a compromised step can do more than fail a build. It can read secrets, alter artifacts, exfiltrate repository data, or use the runner’s trust to reach downstream systems. In GitHub Actions, that risk rises when the workflow has broad token scope, access to deployment credentials, or permission to write back to the repository.

Failure mechanism: An attacker supplies text that is later interpolated into a shell command, then uses shell metacharacters or option injection to change what the runner executes.

Impact: The workflow may leak secrets, modify releases, create persistence in the repository or pipeline, or execute commands with the privileges of the job token and runner environment.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP Non-Human Identity Top 10 addresses the attack and risk surface, while OWASP ASVS, CIS Controls v8 and NIST SP 800-53 Rev 5 set the governance and control requirements practitioners need to meet.

Framework	Control / Reference	Relevance
OWASP ASVS	V1 — Encoding and Sanitization	Shell injection prevention depends on treating untrusted text as data before execution.
Recommendation — Validate and encode untrusted workflow values before they reach a shell command.
CIS Controls v8	CIS-16 — Application Software Security	Workflow scripts are code that must be designed and reviewed for injection risk.
Recommendation — Review CI/CD scripts for injection paths and harden command construction.
NIST SP 800-53 Rev 5	SI-10 — Information Input Validation	Untrusted workflow inputs must be validated before they influence command execution.
	AC-6 — Least Privilege	Limiting job permissions reduces the blast radius if a shell step is exploited.
Recommendation — Validate and constrain all externally influenced inputs before shell use. Restrict job and token permissions to the minimum needed for the step.
OWASP Non-Human Identity Top 10	NHI-06 — Insecure Cloud Deployment Configurations	GitHub Actions runner and workflow configuration can create exploitable execution paths.
Recommendation — Harden workflow and runner configuration to prevent unsafe command execution paths.

Practitioner Guidance

What to verify: Verify that every shell step has a fixed command shape and that untrusted values only enter as quoted data, environment variables, or explicit tool inputs. If a step has to parse user-controlled text, treat that as a design exception rather than a routine pattern.

Common mistake: The usual failure is assuming that one layer of quoting is enough. In practice, the risky pattern is command construction from workflow context, then partial sanitisation, then a final shell parse that still has room to reinterpret characters.

Practitioner takeaway: The safest workflow is the one that does not ask the shell to interpret untrusted text at all; when that is impossible, reduce the shell’s role to a narrow, auditable transport layer for already-validated data.