GitHub Actions Variables, Secrets and Environments Explained

Pipelines need URLs, credentials and settings that do not belong in code. In this lesson you will use environment variables, configuration variables and secrets in GitHub Actions, control GITHUB_TOKEN permissions and protect deployments with environments.

---

🔐 Configuration Without Hard-Coding

Pipelines need values that should not be written into code: URLs, user names, API keys, passwords. GitHub Actions offers three mechanisms:

Mechanism	For	Visible in logs	Set in
Environment variables (env)	Values defined in the workflow file	Yes	The YAML file
Configuration variables (vars)	Non-secret settings (URLs, flags)	Yes	Settings, Secrets and variables, Actions, Variables
Secrets (secrets)	Passwords, tokens, keys	No (masked as ***)	Settings, Secrets and variables, Actions, Secrets

---

🌱 Environment Variables in YAML

env:                               # workflow level
  CI: true

jobs:
  test:
    runs-on: ubuntu-latest
    env:                           # job level
      BROWSER: chromium
    steps:
      - name: Print
        env:                       # step level (most specific wins)
          GREETING: hello
        run: echo "$GREETING from $BROWSER"

Read them in your code with process.env.BROWSER (Node), os.environ["BROWSER"] (Python) or $BROWSER in the shell.

---

⚙️ Configuration Variables (vars)

Create Settings, Secrets and variables, Actions, Variables, New repository variable, e.g. BASE_URL = https://staging.example.com:

- run: npx playwright test
  env:
    BASE_URL: ${{ vars.BASE_URL }}

Use variables for anything you want to change without editing workflow files and that is not secret.

---

🗝️ Secrets

Create Settings, Secrets and variables, Actions, Secrets, New repository secret, e.g. TEST_PASSWORD:

- name: Run tests
  run: npx playwright test
  env:
    TEST_USER: ${{ vars.TEST_USER }}
    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}

Rules worth knowing:

• Secret values are masked in logs; mask other dynamic values with echo "::add-mask::$VALUE".
• Secrets are not passed to workflows triggered by pull requests from forks (to protect them from untrusted code).
• You cannot read a secret back in the UI; you can only update or delete it.
• Do not pass secrets on the command line of tools that print their arguments; prefer environment variables.
• Secret names are case-insensitive and cannot start with GITHUB_.

The automatic GITHUB_TOKEN

Every run gets a temporary GITHUB_TOKEN for the repository, available as ${{ secrets.GITHUB_TOKEN }}. Grant only the permissions you need:

permissions:
  contents: read
  pull-requests: write     # e.g. to comment on PRs

For access to other repositories, use a fine-grained personal access token or a GitHub App, stored as a secret.

---

🌍 Environments

An environment (Settings, Environments) represents a deployment target such as qa, staging or production. Environments add:

Feature	What it does
Environment secrets and variables	Different values per environment, e.g. BASE_URL
Required reviewers	A person must approve before the job runs
Wait timer	Delay before deployment
Deployment branches and tags	Only allowed branches (e.g. main) can deploy

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}      # the staging environment's secret

  smoke-test-staging:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npx playwright install --with-deps chromium
      - run: npx playwright test --grep @smoke
        env:
          BASE_URL: ${{ vars.BASE_URL }}            # the staging URL

  deploy-production:
    needs: smoke-test-staging
    runs-on: ubuntu-latest
    environment: production                       # waits for a required reviewer
    steps:
      - run: ./deploy.sh

Each environment’s variables and secrets override repository-level ones with the same name. The Actions summary shows the deployment history per environment. Full pipelines are in Deploy with GitHub Actions.

---

🏢 Organisation Variables and Secrets

In an organisation, Settings, Secrets and variables, Actions lets admins create values shared with all or selected repositories, such as a common Slack webhook or test-environment URL.

---

🧪 Example: Same Tests, Different Environments

on:
  workflow_dispatch:
    inputs:
      target:
        type: environment
        description: Which environment to test

jobs:
  e2e:
    runs-on: ubuntu-latest
    environment: ${{ inputs.target }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npx playwright install --with-deps
      - run: npx playwright test
        env:
          BASE_URL: ${{ vars.BASE_URL }}
          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}

The test code reads process.env.BASE_URL, as in environment variables with .env.

---

📝 Assignment

1. Add a repository variable BASE_URL and a secret TEST_PASSWORD to a practice repository.
2. Print the variable in a workflow and confirm the secret shows as *** in logs.
3. Create two environments, qa and staging, each with its own BASE_URL.
4. Add a required reviewer to staging and run a job that targets it; approve it.
5. Set permissions: contents: read and observe what happens if a step tries to push.
6. Build a manual workflow whose input chooses the environment to test.

---

❓ FAQ

🤔 What is the difference between vars and secrets in GitHub Actions?

vars are plain configuration values visible in logs; secrets are encrypted and masked. Use secrets for passwords, tokens and keys.

🤔 How do I use a secret in a GitHub Actions workflow?

Create it in Settings, Secrets and variables, Actions, then reference it with ${{ secrets.NAME }}, usually as an environment variable of a step.

🤔 What is GITHUB_TOKEN?

An automatically created, short-lived token for the repository, available in every workflow run; its permissions are set with the permissions key.

🤔 What are GitHub environments?

Named deployment targets with their own secrets and variables and optional protection rules such as required reviewers and allowed branches.

🤔 Why are my secrets empty in a pull request from a fork?

GitHub does not pass secrets to workflows triggered by forks, to protect them from untrusted code.

---

🎯 Next Steps

• 🧩 GitHub Actions Intermediate Concepts
• 🧮 Matrix Builds, Caching and Artifacts
• 📘 Git and GitHub Tutorial: full course