gh secret set: Usage, Options & Common CI Errors

Set encrypted Actions secrets at the repo, environment, or org level.

gh secret set creates or updates an encrypted secret for GitHub Actions. It can read the value from stdin, a flag, or a .env file, and target a repo, a deployment environment, or an organization.

What it does

gh secret set <name> encrypts a value with the target’s public key and stores it as an Actions secret. Scope it to a repo (default), an environment (--env), or an org (--org with --visibility). Reading the value from stdin or --body avoids it appearing in shell history.

Common usage

# Set a repo secret from stdin (no value in history)
echo "$API_KEY" | gh secret set API_KEY

# Set with an inline value
gh secret set API_KEY --body "$API_KEY"

# Environment-scoped and org-scoped secrets
gh secret set DEPLOY_KEY --env production --body "$KEY"
gh secret set NPM_TOKEN --org my-org --visibility all --body "$TOKEN"

Common error in CI: prompts for value / insufficient permissions

gh secret set hangs prompting for a value when none is piped, or fails with HTTP 403 because the token lacks admin rights on the repo/org. Fix: always supply the value via stdin or --body in CI; setting Actions secrets requires admin access (repo admin, or org owner for org secrets) - the default GITHUB_TOKEN cannot manage secrets, so use a PAT or GitHub App token with admin:repo/admin:org. For org secrets, --visibility (all/private/selected) is required.

Key options

Related guides