Environments in GitHub Actions

GitHub Actions is a great tool for automating software workflows, and one of its standout features is environments. This functionality allows you to handle different stages of your project, like development, staging, and production, each with its own set of configurations and secrets. Here’s a straightforward guide on how to set up and use environments in GitHub Actions, and why they’re so handy.

What are environments?

Environments in GitHub Actions help you manage different settings for your project phases. You can define specific configurations, secrets, and deployment strategies for each environment directly in your GitHub repository settings.

How to set up environments with specific secrets and variables

1. Define your environments: Go to your repository settings and add environments like production, staging, or test under the “Environments” section.
2. Configure secrets and variables: Select an environment and click on “Secrets” then “Add secret” to set up unique secrets like API keys, which are only accessible to actions running in that environment.
3. Use environments in your workflows: In your workflow file (.github/workflows/my-workflow.yml), specify the environment using the environment keyword. This controls which settings and secrets are used based on the environment specified.

Example: Deploying to production

name: Deploy to Production
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - run: npm install
    - run: npm run build
    - run: npm run deploy
      env:
        API_KEY: ${{ secrets.API_KEY }}

In this workflow, the API_KEY will be specific to the production environment, ensuring the right settings are used during deployment.

Example: Deploying to staging with ephemeral environment URL

When setting up environments, you can also specify an environment URL. This URL is useful as it appears in pull requests associated with the environment, providing a direct link to view the deployment or relevant resources.

Here’s how you can specify an environment URL in your workflow:

name: Deploy to staging with ephemeral environment URL
on:
  pull_request:
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: ${{ steps.deploy.outputs.url }}
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - run: npm install
    - run: npm run build
    - run: npm run deploy
      env:
        API_KEY: ${{ secrets.API_KEY }}
    - id: deploy
      run: echo "url=https://staging-pr-${{ github.event.pull_request.number }}.example.com" >> $GITHUB_OUTPUT

Environment URL can either be static or dynamic ↗. In the example above, the URL is dynamic and changes based on the PR number.

Why use environments?

• Security: Keeping secrets specific to an environment reduces the risk of exposure, as they aren’t accessible outside their designated environment.
• Controlled deployments: You can set environments to require manual approvals ↗ or other complex deployment protection rules, adding an extra layer of oversight before changes go live, which is especially useful for production environments.
• Audit trails and notifications: GitHub tracks who accesses each environment and when, providing clear audit trails. You can also set up notifications for actions related to your environments, keeping you informed about deployments.