The foundation of robust Continuous Integration and Continuous Deployment (CI/CD) pipelines rests on the ability to dynamically configure execution environments. In GitHub Actions, this configurability is achieved through environment variables, which serve as the primary mechanism for injecting context, secrets, and configuration data into workflow jobs. Understanding the hierarchy, scope, and retrieval methods of these variables is critical for developers seeking to build reproducible, secure, and efficient automation workflows. Unlike static configuration files, environment variables allow for runtime adjustments based on the triggering event, the target runner, or the specific phase of the build process. This technical analysis examines the full spectrum of GitHub Actions environment variables, ranging from the 18 default system variables to user-defined contexts and platform-specific implementations.
Default GitHub Actions Environment Variables
Every GitHub Actions workflow, regardless of the complexity or the target operating system, is automatically populated with a set of default environment variables. These variables provide fundamental context about the execution environment, the repository, and the specific run instance. There are exactly 18 default environment variables available to any workflow or shell script running within GitHub Actions. These variables are prefixed with the string GITHUB and offer immutable data points that define the current execution state.
The default variables include:
- CI: Indicates that the build is running in a continuous integration environment.
- GITHUB_WORKFLOW: The name of the workflow.
- GITHUB_RUN_ID: The unique identifier for the specific workflow run.
- GITHUB_RUN_NUMBER: The sequential number of the workflow run for the repository.
- GITHUB_ACTION: The unique identifier of the currently executing action.
- GITHUB_ACTIONS: A boolean flag indicating the presence of the GitHub Actions runner.
- GITHUB_ACTOR: The username of the user that initiated the workflow run.
- GITHUB_REPOSITORY: The owner and repository name in the format owner/repo.
- GITHUB_EVENT_NAME: The name of the event that triggered the workflow (e.g., push, pull_request).
- GITHUB_EVENT_PATH: The path to the file on the runner that contains the webhook payload of the event.
- GITHUB_WORKSPACE: The default path where the repository code is checked out.
- GITHUB_SHA: The commit SHA being built or tested.
- GITHUB_REF: The branch or tag ref that triggered the workflow.
- GITHUB_HEAD_REF: The head branch name for pull requests; empty for other triggers.
- GITHUB_BASE_REF: The base branch name for pull requests; empty for other triggers.
- GITHUB_SERVER_URL: The URL of the GitHub server (e.g., https://github.com).
- GITHUB_API_URL: The URL for the GitHub REST API.
- GITHUB_GRAPHQL_URL: The URL for the GitHub GraphQL API.
These variables are accessible via standard shell syntax (e.g., $GITHUB_WORKFLOW) when running in a shell environment, or through the github context in the workflow YAML file. They provide the essential metadata required for logging, conditional logic, and API interactions without requiring manual configuration by the developer.
Platform-Specific and Runner Environment Variables
Beyond the 18 default variables, the actual number of environment variables available during a workflow execution depends heavily on the runner image being used. The GitHub-hosted runners, such as ubuntu-latest, windows-latest, and macos-latest, each maintain a distinct set of environment variables defined by their respective operating systems and pre-installed software stacks.
For example, a build running on the ubuntu-latest image has access to over 60 additional GitHub Actions environment variables. These variables are specific to the Linux distribution and include paths to compilers, package managers, and other tools installed by default on that image. Similarly, the macos-latest runner may have a different set of variables, potentially offering more or fewer options depending on the specific version of macOS and the tools pre-installed on that runner image. The windows-latest runner also maintains its own set of variables, such as the PATH variable, which is configured differently than its Unix counterparts.
Developers should not assume that a variable available on one runner is available on another. The variability in these "standard issue" variables across distributions means that workflows must be written with platform-specific awareness. To inspect the full list of variables available in a specific runner environment, developers can execute a simple workflow that prints the environment variables using the env command.
yaml
name: Publish GitHub Actions Artifacts Example
on:
push:
branches: [ main ]
jobs:
github-actions-environment-variables-ubuntu:
runs-on: ubuntu-latest
steps:
- name: List of the GitHub Actions environment variables on Windows
run: env
github-actions-environment-variables-windows:
runs-on: windows-latest
steps:
- name: Ubuntu GitHub Actions environment variables List
run: env
github-actions-environment-variables-macos:
runs-on: macos-latest
steps:
- name: MacOs List of GitHub Actions environment variables
run: env
When this workflow executes, the env command forces each container to print out all its environment variables to the console. This output provides a comprehensive, real-time view of the variables available for that specific runner, allowing developers to identify platform-specific paths, tool locations, and configuration values that can be leveraged in their build scripts.
User-Defined Variables and Scope Hierarchy
While default and runner-specific variables provide context, user-defined environment variables allow developers to dynamically alter how a workflow, job, or step behaves. These variables can be set at three distinct levels: workflow, job, and step. Each level defines the scope and visibility of the variable, determining which parts of the pipeline can access the data.
Workflow-level environment variables are declared at the top of the workflow file and apply to every job and step within that workflow. This is an effective strategy for defining global configuration, such as the target environment for deployment (e.g., development, testing, or production). For instance, in Node.js applications, the NODE_ENV variable is commonly set at the workflow level to ensure that all subsequent jobs configure their behavior appropriately for that specific environment.
yaml
env:
NODE_ENV: production
Job-level environment variables limit the scope of the variable to a specific job. This is useful when different jobs require different configurations, such as varying build flags or test parameters. Step-level environment variables are the most granular, limiting the scope to a single step within a job. This is particularly useful for tasks that require temporary configuration, such as defining file paths for input or output files specific to that step.
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Print name
env:
NAME: Mona
run: echo "Hello $NAME"
To access these user-defined variables within a shell script, developers must use standard UNIX environment variable syntax, prefixing the variable name with a dollar sign (e.g., $NAME). When the workflow runs, the run command will expand these variables and execute the command with the substituted values.
The Env Context and Variable Retrieval
A critical distinction in GitHub Actions is the difference between accessing environment variables in a shell script versus accessing them within the workflow YAML file itself. In shell scripts, variables are accessed via the $VARIABLE_NAME syntax. However, within the workflow file, variables are accessed through the env context.
The env context is an object that maps variable names to their values. This context changes for each step in a job, reflecting the cumulative effect of workflow, job, and step-level definitions. Developers can retrieve the values of variables stored in the env context and use them in any key within a workflow step, with the exception of the id and uses keys.
yaml
steps:
- name: Use context
env:
first_name: Mona
super_duper_var: totally_awesome
run: echo "$first_name $super_duper_var"
If a developer attempts to use an environment variable within the YAML syntax without utilizing the context, or if they try to access a variable defined in a different scope without proper context resolution, the workflow will fail. For example, if a variable is set in one step but accessed in another without being defined in the env block of the second step, it will not be available. Furthermore, when using actions (such as actions/setup-java), the action runs in its own isolated environment. Therefore, to pass a user-defined variable to an action, the variable must be explicitly passed through the action's with inputs or defined in the env block of the step that calls the action. Attempting to access a user-defined variable directly within an action without using the env context or passing it as an input will result in an error, as the action does not have access to the same environment scope.
GitHub Secrets for Secure Variable Management
The final and most critical category of environment variables in GitHub Actions is GitHub secrets. Secrets are encrypted environment variables that allow developers to store sensitive information, such as passwords, API keys, and tokens, without exposing them in the repository's code or logs.
When a secret is defined in the repository settings, GitHub encrypts the value and injects it into the workflow runtime as an environment variable. This ensures that the sensitive data is never visible in the workflow history or the repository code. Developers should always use GitHub secrets for any variable that contains sensitive information.
To use a secret in a workflow, developers reference it using the secrets context, similar to how they use the env context.
yaml
steps:
- name: Use secret
run: echo "My secret is ${{ secrets.MY_SECRET }}"
This approach provides an extra layer of security to CI/CD pipelines. By separating sensitive data from the workflow configuration, organizations can maintain compliance with security standards and reduce the risk of credential leakage. Integrating tools like Snyk into the GitHub Actions pipeline can further enhance security by scanning code, containers, open source dependencies, and Infrastructure as Code (IaC) for vulnerabilities, ensuring that the entire deployment process is secure.
Conclusion
Mastering GitHub Actions environment variables is essential for building efficient, secure, and flexible CI/CD pipelines. The hierarchy of variables—from the 18 default system variables to platform-specific runner variables, user-defined scoped variables, and encrypted secrets—provides developers with granular control over the execution environment. By understanding the scope and retrieval methods for each type of variable, developers can create workflows that are adaptable to different operating systems, configurable for various deployment targets, and secure against credential exposure. The ability to inspect and utilize these variables effectively ensures that automation pipelines are not only functional but also robust and maintainable.