Environment variables and configuration variables serve as the foundational mechanism for storing, reusing, and injecting configuration data into GitHub Actions workflows. These variables allow developers to decouple configuration from code, enabling dynamic behavior based on context, environment, or repository settings. GitHub Actions provides a robust system for managing non-sensitive configuration information through custom variables and default environment variables, while sensitive data is handled through an encrypted secrets system. Understanding the scope, precedence, and syntax of these variables is critical for building reliable, secure, and maintainable CI/CD pipelines.
Variable Types and Scope Hierarchy
Variables in GitHub Actions can be categorized into three primary types: default environment variables, custom configuration variables, and secrets. Custom variables are used for non-sensitive configuration data such as compiler flags, server names, or usernames. They can be defined at the workflow, job, or step level within a YAML file, or at the organization, repository, or environment level through the GitHub interface. The scope of a variable determines where it is accessible within a workflow run.
Workflow-level environment variables apply to the entire workflow and are defined at the top level of the YAML file using the env key. Job-level environment variables apply only to specific jobs, while step-level environment variables are limited to a single step. Configuration variables can be defined at the organization, repository, or environment level, allowing for cross-workflow reuse. When variables are defined at multiple levels with the same name, the variable at the lowest level takes precedence. For example, a repository-level variable overrides an organization-level variable, and an environment-level variable overrides both repository and organization-level variables.
yaml
name: CI Pipeline
env:
NODE_ENV: production
The precedence hierarchy ensures that specific configurations override general ones. However, environment-level variables are only available on the runner after the job starts executing, meaning they do not overwrite variables in the env and vars contexts during the initial setup phase. For reusable workflows, the variables from the caller workflow's repository are used, ensuring consistency across shared workflow definitions.
Default Environment Variables and Contexts
GitHub automatically sets default environment variables that are available to every step in a workflow. These variables provide access to essential information about the repository, the action, and the runner. Because these variables are set by GitHub and not defined in the workflow file, they are not accessible through the env context. Instead, most default variables have corresponding context properties that allow for proper access during workflow processing. For example, the value of the GITHUB_REF variable can be read using the ${{ github.ref }} context property.
The CI variable is a notable default environment variable that is always set to true. While it is currently possible to overwrite the CI variable, this behavior is not guaranteed to persist in future updates. Variables prefixed with GITHUB_ and RUNNER_ cannot be overwritten by user-defined values. If an attempt is made to override these default variables, the assignment is ignored. Developers can list the entire set of environment variables available to a workflow step by using run: env in a step and examining the output.
bash
run: env
GitHub strongly recommends that actions use variables to access the filesystem rather than relying on hardcoded file paths. This approach ensures compatibility across different runner environments, as GitHub sets variables for actions to use consistently. The use of contexts, such as github, env, and vars, is required to make these variables available to actions that do not share the same environment as the step in which they are defined.
Custom Variable Definition and Syntax
Custom variables can be defined in two primary ways: within the workflow file using the env key, or at the organization, repository, or environment level through the GitHub settings. When defining variables in the workflow file, the syntax follows standard UNIX environment variable conventions. For example, a variable named NAME is accessed by prefixing it with a dollar sign, resulting in $NAME.
yaml
jobs:
build:
runs-on: ubuntu-latest
env:
NAME: MyApplication
steps:
- name: Print Name
run: echo "Application is $NAME"
At the configuration level, variables defined at the organization, repository, or environment level are accessed using the vars context. For instance, a repository-level variable named API_ENDPOINT is accessed using ${{ vars.API_ENDPOINT }}. This separation between env and vars contexts allows for clear distinction between workflow-specific variables and broader configuration settings.
Job-level environment variables are defined within the job block and apply to all steps within that job. Step-level environment variables are defined within the step block and are limited to that specific step. This granularity allows for precise control over variable scope, which is useful for tasks such as defining file paths for input or output files specific to a step.
yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Configure Java
uses: actions/setup-java@v3
with:
java-version: '17'
- name: Build
env:
MAVEN_OPTS: '-Xms256m -Xmx512m'
run: mvn clean install
GitHub Secrets for Sensitive Data
For sensitive information such as passwords, API authorization keys, or tokens, GitHub provides a secrets system. Secrets are encrypted and stored securely, preventing accidental exposure in logs or repositories. To create a secret, users navigate to the repository settings, select "Secrets and variables," and then choose "Actions." From there, they can create a new repository secret by entering a name and a value.
Secrets are accessed within workflows using the secrets context, prefixed with ${{ secrets. }}. For example, a secret named API_KEY is accessed using ${{ secrets.API_KEY }}. When a secret is used in a workflow, GitHub automatically masks its value in the logs to prevent accidental exposure. This masking ensures that even if the secret is printed or logged, its value is obscured.
yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to Production
run: ./deploy.sh --api-key ${{ secrets.API_KEY }}
Naming Conventions and Limitations
Variables and secrets in GitHub Actions must adhere to specific naming conventions to ensure proper functionality and security. Spaces are not allowed in variable or secret names. Names must not start with the GITHUB_ prefix, as this prefix is reserved for default environment variables. Additionally, names must not start with a number. Secret names are stored as uppercase regardless of how they are entered, and they are case-insensitive when referenced.
Variable names must be unique within the repository, organization, or enterprise where they are created. This uniqueness requirement prevents conflicts and ensures that the correct variable is accessed during workflow execution. The naming conventions also apply to custom variables defined in the workflow file, ensuring consistency across the platform.
Implementation Examples
The following example demonstrates a complete GitHub Actions workflow that utilizes workflow-level, job-level, and step-level environment variables, as well as GitHub secrets. The workflow builds a Java application using Maven and prints the value of the NAME variable.
```yaml
name: Java CI
env:
NAME: MyJavaApp
jobs:
build:
runs-on: ubuntu-latest
env:
JAVA_VERSION: '17'
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Java
uses: actions/setup-java@v3
with:
java-version: ${{ env.JAVA_VERSION }}
- name: Print Name
env:
GREETING: "Hello from"
run: echo "${{ env.GREETING }} ${{ env.NAME }}"
- name: Build
run: mvn clean install
```
In this example, NAME is a workflow-level variable, JAVA_VERSION is a job-level variable, and GREETING is a step-level variable. The env context is used to access these variables within the workflow. If a secret were used, it would be accessed via the secrets context.
Security Considerations and Best Practices
By default, variables render unmasked in build outputs, which can expose sensitive information if not handled carefully. For this reason, secrets should be used for any data that requires greater security, such as passwords or API keys. Secrets are encrypted and masked in logs, reducing the risk of accidental exposure.
When defining configuration variables at the organization level, administrators can use policies to limit access by repository. For example, access can be granted to all repositories, or limited to only private repositories or a specified list of repositories. This granular control enhances security by ensuring that sensitive configuration data is only available where necessary.
Conclusion
GitHub Actions provides a comprehensive system for managing environment variables, configuration variables, and secrets. By understanding the scope, precedence, and syntax of these variables, developers can build robust and secure CI/CD pipelines. The ability to define variables at multiple levels, from workflow to organization, allows for flexibility and reuse across projects. The use of contexts, such as env, vars, and secrets, ensures that variables are accessed correctly and securely. As workflows become more complex, adherence to naming conventions and security best practices becomes increasingly important. The automatic masking of secrets and the precedence hierarchy for variables provide a solid foundation for managing configuration data in GitHub Actions.