github-secrets

GitHub Secrets & Variables

GitHub secrets and variables exist at three scopes with strict precedence rules. Getting the scope wrong causes silent failures — empty values with no error.

Scope Hierarchy

Organization  →  Repository  →  Environment
(broadest)                      (most specific, wins ties)

• Organization: shared across repos, set with --org
• Repository: default scope, no flag needed inside a repo
• Environment: requires --env flag AND environment: in the workflow job

Environment > Repository > Organization when names collide.

Secrets vs Variables — Quick Reference

	Secrets (secrets.*)	Variables (vars.*)
CLI	gh secret	gh variable
Workflow	${{ secrets.NAME }}	${{ vars.NAME }}
Encrypted	Yes	No
Readable after set	No (write-only)	Yes
Use for	Tokens, passwords, keys	URLs, flags, config

These are different namespaces. secrets.X and vars.X are not interchangeable.

Critical Rules

Always check before setting

# Secrets — can only check existence, not value
gh secret list [--org ORG] [--env ENV] | grep -q "^NAME"

# Variables — can check existence AND value
gh variable list [--org ORG] [--env ENV] --json name,value

Never try to read secret values

There is no gh secret get. Secrets are write-only. gh secret list shows names only. To update, re-set from the source of truth.

Environment secrets require environment: in the job

jobs:
  deploy:
    environment: production    # WITHOUT THIS, environment secrets are invisible
    steps:
      - run: echo "${{ secrets.PROD_SECRET }}"

This is the single most common mistake. Missing environment: produces empty values with zero warnings.

Scope flags are required and specific

gh secret set X --body "v"                    # repo (default)
gh secret set X --org my-org --body "v"       # org
gh secret set X --env production --body "v"   # environment