Secrets and Variables — Understanding GitHub CLI

GitHub CLI manages secrets (encrypted values) and variables (plain-text configuration) used by GitHub Actions, Dependabot, and Codespaces.

Secrets (`gh secret`)

Secrets are encrypted and only exposed to workflows at runtime. They are used for tokens, passwords, API keys, and other sensitive values.

Setting a Secret

# Set from a prompt (interactive, hidden input)
gh secret set MY_SECRET
 
# Set from a value
gh secret set MY_SECRET --body "supersecretvalue"
 
# Set from a file
gh secret set MY_SECRET < secret.txt
 
# Set from an environment variable
echo "$API_KEY" | gh secret set MY_SECRET
 
# Set for a specific environment
gh secret set MY_SECRET --env production
 
# Set for an organization
gh secret set MY_SECRET --org my-org
 
# Scope an org secret to specific repos
gh secret set MY_SECRET --org my-org --repos "repo1,repo2"
 
# Set for Dependabot
gh secret set MY_SECRET --app dependabot
 
# Set for Codespaces
gh secret set MY_SECRET --app codespaces

Listing Secrets

# Repository secrets
gh secret list
 
# Environment secrets
gh secret list --env production
 
# Organization secrets
gh secret list --org my-org
 
# Dependabot secrets
gh secret list --app dependabot
 
# JSON output
gh secret list --json name,updatedAt

Deleting a Secret

gh secret delete MY_SECRET
 
# Delete an environment secret
gh secret delete MY_SECRET --env production
 
# Delete an org secret
gh secret delete MY_SECRET --org my-org

Variables (`gh variable`)

Variables are plain-text configuration values (not encrypted). They are used for non-sensitive settings like environment names, feature flags, and URLs.

Setting a Variable

# Set from a value
gh variable set MY_VAR --body "some-value"
 
# Set from a prompt
gh variable set MY_VAR
 
# Set for a specific environment
gh variable set MY_VAR --env staging --body "staging-url"
 
# Set for an organization
gh variable set MY_VAR --org my-org --body "shared-value"
 
# Scope an org variable to specific repos
gh variable set MY_VAR --org my-org --repos "repo1,repo2"

Getting a Variable

gh variable get MY_VAR
 
# Get an environment variable
gh variable get MY_VAR --env production
 
# Get an org variable
gh variable get MY_VAR --org my-org

Listing Variables

# Repository variables
gh variable list
 
# Environment variables
gh variable list --env production
 
# Organization variables
gh variable list --org my-org
 
# JSON output
gh variable list --json name,value,updatedAt

Deleting a Variable

gh variable delete MY_VAR
 
# Delete an environment variable
gh variable delete MY_VAR --env staging
 
# Delete an org variable
gh variable delete MY_VAR --org my-org

Scope Summary

Scope	Secrets	Variables	Used By
Repository	`gh secret set`	`gh variable set`	Actions, Dependabot
Environment	`--env <name>`	`--env <name>`	Actions
Organization	`--org <name>`	`--org <name>`	Actions, Dependabot
User	`--app codespaces`	—	Codespaces

Using in Workflows

Once set, secrets and variables are accessible in your workflow YAML:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          API_KEY: ${{ secrets.MY_SECRET }}
          DEPLOY_URL: ${{ vars.MY_VAR }}
        run: ./deploy.sh

Bulk Operations

Set multiple secrets or variables from an .env file:

# Set multiple secrets from .env
while IFS='=' read -r key value; do
  echo "$value" | gh secret set "$key"
done < .env

Exercises

Set a test secret: gh secret set TEST_SECRET --body "hello"
List secrets: gh secret list
Set a test variable: gh variable set TEST_VAR --body "world"
Get the variable: gh variable get TEST_VAR
Clean up: gh secret delete TEST_SECRET && gh variable delete TEST_VAR