How to Manage GitHub Environment Secrets and Variables via CLI

This guide explains how to use the GitHub CLI (gh) to manage configuration data for your environments. This is particularly useful for CI/CD pipelines where you need to toggle between “Production,” “Staging,” or “Development” settings.

Prerequisites

1. GitHub CLI Installed: Ensure you have the gh tool installed (brew install gh on macOS or sudo apt install gh on Linux).
2. Authenticated: Run gh auth login to link your account.
3. Environment Created: Ensure the environment (e.g., production) already exists in your repository settings.

1. Understanding Secrets vs. Variables

• Secrets: Encrypted. Used for sensitive data like API keys, passwords, or SSH keys. They cannot be viewed once set.
• Variables: Plain text. Used for non-sensitive data like configuration flags, URLs, or environment names.

2. Setting Environment Secrets

To set a secret for a specific environment, use the secret set command with the --env flag.

Command Syntax:

gh secret set SECRET_NAME --env environment_name

gh secret set SECRET_NAME --env environment_name

Example: To set a database password for your “production” environment:

gh secret set DB_PASSWORD --env production --body "your_secure_password"

gh secret set DB_PASSWORD --env production --body "your_secure_password"

Alternatively, if you omit --body, the CLI will open an interactive prompt for you to paste the secret securely.

3. Setting Environment Variables

Variables use a similar syntax but utilize the variable command.

Command Syntax:

gh variable set VARIABLE_NAME --env environment_name

gh variable set VARIABLE_NAME --env environment_name

Example: To set the API endpoint for your “staging” environment:

gh variable set API_URL --env staging --body "https://staging.api.turbogeek.co.uk"

gh variable set API_URL --env staging --body "https://staging.api.turbogeek.co.uk"

4. Verifying Your Settings

You can list all secrets or variables assigned to an environment to ensure they were created correctly.

• To list secrets: gh secret list --env production
• To list variables: gh variable list --env production

5. Using them in GitHub Actions

Once set via the CLI, these are accessed in your .github/workflows/deploy.yml file by referencing the environment:

YAML

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # This links the job to the environment
    steps:
      - name: Deploy to Server
        env:
          API_KEY: ${{ secrets.DB_PASSWORD }}
          API_URL: ${{ vars.API_URL }}
        run: ./deploy.sh

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # This links the job to the environment
    steps:
      - name: Deploy to Server
        env:
          API_KEY: ${{ secrets.DB_PASSWORD }}
          API_URL: ${{ vars.API_URL }}
        run: ./deploy.sh

Quick Reference Table

Pro Tip: Bulk-Uploading from a .env File

Manually typing out twenty different variables is error-prone and tedious. If you have a local .env file, you can use a small Bash loop to pipe those values directly into the GitHub CLI.

The Shell Script

Run this command from your terminal in the same directory as your .env file. Replace production with your target environment name.

while read -r line || [ -n "$line" ]; do
  # Skip comments and empty lines
  [[ "$line" =~ ^#.*$ ]] || [[ -z "$line" ]] && continue
  
  # Split into Name and Value
  key=$(echo "$line" | cut -d '=' -f 1)
  value=$(echo "$line" | cut -d '=' -f 2-)
  
  echo "Setting variable: $key"
  gh variable set "$key" --env production --body "$value"
done < .env

while read -r line || [ -n "$line" ]; do
  # Skip comments and empty lines
  [[ "$line" =~ ^#.*$ ]] || [[ -z "$line" ]] && continue
  
  # Split into Name and Value
  key=$(echo "$line" | cut -d '=' -f 1)
  value=$(echo "$line" | cut -d '=' -f 2-)
  
  echo "Setting variable: $key"
  gh variable set "$key" --env production --body "$value"
done < .env

How it works:

1. while read -r line: Reads your .env file line by line.
2. [[ "$line" =~ ^#.*$ ]]: This logic ensures the script ignores any comments (lines starting with #) or blank lines in your file.
3. cut -d '=': This splits the line at the first = sign to separate the variable name from the data.
4. gh variable set: Feeds the parsed data directly into the CLI.

Handling Secrets vs. Variables

If your .env file contains sensitive data (like passwords), simply change the command inside the loop from gh variable set to gh secret set.

Warning: Be careful when bulk-uploading secrets. Ensure your terminal history doesn’t save the values by using a space before your command or clearing your history afterwards.

Comparison: Manual vs. Bulk Upload

Related reading

• GitHub CLI Secrets: Automate Branch Protection Rulesets
• How to Delete All GitHub Actions Workflow Runs with the GitHub CLI (gh)
• How to Install and Use the GitHub CLI (gh) on Ubuntu (Step-by-Step): Step-by-Step Guide