GitHub Actions workflows are driven by a dynamic set of contexts that provide crucial information to the execution environment. These contexts, primarily env, github, and strategy, act as the nervous system of a CI/CD pipeline, allowing steps to access environment variables, event data, and matrix configuration details. Understanding the scope, availability, and security implications of these contexts is essential for building robust, secure, and efficient automation workflows. The env context manages variable state across workflow levels, the github context provides metadata about the triggering event and runner, and the strategy context handles parallel execution logic. Each context has specific constraints on where it can be used within a workflow file, and some contain sensitive data that requires careful handling to prevent security vulnerabilities.
The Env Context and Variable Scope
The env context is a fundamental mechanism for passing configuration data to steps within a GitHub Actions workflow. It is an object that changes for each step in a job, yet it can be accessed from any step within that job. This context does not contain variables inherited by the runner process itself; rather, it contains variables explicitly set in the workflow file. To retrieve the values of variables stored in the env context, users can use them in any key of a workflow step, with the exception of the id and uses keys.
The structure of the env context is a mapping of variable names to their values. The contents of this context can change depending on where it is used in the workflow run, reflecting variables set at the workflow, job, and step levels. For example, a context might contain variables such as:
json
{
"first_name": "Mona",
"super_duper_var": "totally_awesome"
}
When a specific environment variable value is needed, it is accessed using the syntax env.<env_name>, which returns a string. However, if a user wants to use the value of a variable inside a runner during a script execution, they must use the runner operating system's normal method for reading environment variables, such as referencing $GITHUB_REF or other system variables. This distinction is critical because the env context is processed by GitHub Actions before the job is sent to the runner, whereas the runner uses its own environment variable resolution.
The GitHub Context and Event Data
The github context is the top-level context available during any job or step in a workflow. It contains a comprehensive set of properties that describe the current workflow run, the event that triggered it, and the runner environment. Most of the data in the github context can be read in environment variables, which allows for flexible integration with scripts and actions. However, users must exercise caution when using the whole github context, as it includes sensitive information such as github.token. While GitHub masks secrets when they are printed to the console, exporting or printing the entire context can inadvertently expose sensitive data.
Security is a primary concern when dealing with the github context. When creating workflows and actions, developers must consider whether their code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert malicious content. Therefore, the secure use of the github context is paramount.
Core GitHub Properties
The github context contains numerous properties that provide detailed information about the workflow execution:
github.action: The name of the action currently running, or the id of a step. GitHub removes special characters, and uses the name__runwhen the current step runs a script without an id. If the same action is used more than once in the same job, the name will include a suffix with the sequence number with an underscore before it. For example, the first script run will have the name__run, and the second will be named__run_2. Similarly, the second invocation ofactions/checkoutwill beactionscheckout2.github.action_path: The path where an action is located. This property is only supported in composite actions. It can be used to access files located in the same repository as the action, for example by changing directories to the path using the environment variable:cd "$GITHUB_ACTION_PATH".github.action_ref: For a step executing an action, this is the ref of the action being executed, for examplev2. Do not use this in therunkeyword. To make this context work with composite actions, reference it within theenvcontext of the composite action.github.action_repository: For a step executing an action, this is the owner and repository name of the action, for exampleactions/checkout. Do not use this in therunkeyword. To make this context work with composite actions, reference it within theenvcontext of the composite action.github.action_status: For a composite action, this indicates the current result of the composite action.github.actor: The username of the user that triggered the initial workflow run. If the workflow run is a re-run, this value may differ fromgithub.triggering_actor. Any workflow re-runs will use the privileges ofgithub.actor, even if the actor initiating the re-run (github.triggering_actor) has different privileges.github.actor_id: The account ID of the person or app that triggered the initial workflow run, for example1234567. Note that this is different from the actor username.github.api_url: The URL of the GitHub REST API.github.base_ref: Thebase_refor target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is eitherpull_requestorpull_request_target.github.env: The path on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job.github.event: The full event webhook payload. This object is identical to the webhook payload of the event that triggered the workflow run and is different for each event. For example, for a workflow run triggered by thepushevent, this object contains the contents of the push webhook payload.github.event_name: The name of the event that triggered the workflow run.github.event_path: The path to the file on the runner that contains the full event webhook payload.github.graphql_url: The URL of the GitHub GraphQL API.github.head_ref: Thehead_refor source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is eitherpull_requestorpull_request_target.github.job: Thejob_idof the current job. This context property is set by the Actions runner and is only available within the execution steps of a job. Otherwise, the value of this property will be null.github.path: The path on the runner to the file that sets system PATH variables from workflow commands. This file is unique to the current step and is a different file for each step in a job.github.ref: The fully-formed ref of the branch or tag that triggered the workflow run.
The Strategy Context and Matrix Execution
The strategy context is used when a workflow employs a matrix strategy to run multiple jobs in parallel. This context provides information about the current job's position within the matrix and the overall strategy configuration.
strategy.fail-fast: A boolean value. When this evaluates to true, all in-progress jobs are canceled if any job in a matrix fails.strategy.job-index: A number representing the index of the current job in the matrix. This is a zero-based number, so the first job's index in the matrix is 0.strategy.job-total: A number representing the total number of jobs in the matrix. This is not a zero-based number. For example, for a matrix with four jobs, the value ofjob-totalis 4.strategy.max-parallel: The maximum number of jobs that can run simultaneously when using a matrix job strategy.
An example of the strategy context contents from a matrix with four jobs, taken from the final job, would include the index of that job and the total count. This context allows for precise control over parallel execution and failure handling in complex workflows.
Context Restrictions and Execution Flow
Different contexts are available throughout a workflow run, and their availability is restricted to specific locations within the workflow file. For example, the secrets context may only be used at certain places within a job. Similarly, some functions may only be used in certain places, such as the hashFiles function, which is not available everywhere.
The if check in a workflow is processed by GitHub Actions, and the job is only sent to the runner if the result is true. Once the job is sent to the runner, the step is executed and refers to variables like $GITHUB_REF from the runner. This distinction is crucial: the if condition is evaluated by GitHub before the job starts, while the step execution happens on the runner. The restrictions on where each context and special function can be used are strictly enforced, and the listed contexts are only available for the given workflow key and may not be used anywhere else.
Conclusion
The env, github, and strategy contexts form the backbone of GitHub Actions workflows, providing essential data for variable management, event handling, and parallel execution. The env context allows for flexible variable scoping across workflow levels, while the github context offers detailed metadata about the workflow run and triggering event. The strategy context enables sophisticated matrix-based parallelism. Understanding the specific properties, availability, and security implications of each context is critical for developing secure and efficient CI/CD pipelines. Developers must be mindful of the restrictions on where these contexts can be used and the potential risks associated with exposing sensitive data, such as tokens, in the github context. By leveraging these contexts correctly, users can build robust automation that responds dynamically to repository events and configuration changes.