gh-secret-set

Set a secret for the current repository (user will be prompted for the value)

$ gh secret set [name]

$ gh secret set [name] < [path/to/file]

$ gh secret set [name] [[-b|--body]] [value] [[-R|--repo]] [owner]/[repository]

$ gh secret set [name] [[-o|--org]] [organization] [[-r|--repos]] "[repository1,repository2,...]"

$ gh secret set [name] [[-o|--org]] [organization] [[-v|--visibility]] [all|private|selected]

gh secret set SECRET_NAME [flags]

Sets a repository secret (default scope):
gh secret set MY_REPO_SECRET

Sets an environment secret:
gh secret set MY_ENV_SECRET --env production

Sets an organization secret:
gh secret set MY_ORG_SECRET --org my-organization

Reads secret value from a file:
gh secret set MY_FILE_SECRET --body path/to/secret.txt

SECRET_NAME
    The name of the secret to create or update. This name must be unique within its scope (repository, environment, or organization).

-R, --repo [HOST/]OWNER/REPO
    Select a different repository to operate on. Defaults to the current repository if not specified.

--body file
    Read the secret value from the specified file path instead of standard input (stdin). Useful for non-interactive scripts.

--env environment-name
    Set the secret for a specific deployment environment within the repository. Requires the environment to exist in GitHub.

--org organization-name
    Set the secret at the organization level. This secret can then be made available to multiple repositories within the organization.

--add-for-repositories repository-list
    For organization secrets, a comma-separated list of repository names (e.g., owner/repo1,owner/repo2) that should have access to the secret. Requires --visibility selected.

--visibility {all|private|selected}
    For organization secrets, defines the access level for repositories. all (all repos), private (internal and private repos), or selected (specific repos using --add-for-repositories).

gh secret set is a command-line tool within the GitHub CLI (gh) designed to manage sensitive data for GitHub Actions workflows. It allows users to securely create or update secrets, which are crucial for storing credentials, API keys, and other non-public information required by CI/CD pipelines. This command supports setting secrets at various scopes:

Repository Level: Secrets are accessible only to workflows within a specific GitHub repository.
Environment Level: Secrets are tied to a specific deployment environment (e.g., production, staging) within a repository, often protected by approval rules.
Organization Level: Secrets can be shared across multiple repositories belonging to the same GitHub organization, with granular control over which repositories have access.

The secret value is typically read from standard input (prompting the user) or from a specified file using the --body flag. gh secret set ensures that secrets are encrypted on the client side before being transmitted to GitHub, enhancing security by preventing the raw secret from being exposed. This command is an essential tool for automating the secure injection of sensitive configuration into GitHub Actions.

Secrets set via gh secret set are encrypted and cannot be retrieved (read) back using the GitHub CLI or API. You must have appropriate write permissions (e.g., admin or maintainer role for repository/environment, or owner for organization) to set secrets. Default input for the secret value is stdin, making it interactive; for scripting, pipe the value or use the --body flag to avoid manual input or shell history issues.

By default, gh secret set prompts interactively for the secret value from standard input. For non-interactive use in scripts, you can pipe the secret value to the command (e.g., echo "my_secret_value" | gh secret set MY_SECRET_NAME) or use the --body flag to read the secret from a file (e.g., gh secret set MY_SECRET_NAME --body secret.txt).

For enhanced security, gh secret set encrypts the secret value on the client side (your machine) before it is sent to GitHub. This ensures that the raw, unencrypted secret never traverses the network, minimizing exposure risk.

The gh CLI, developed by GitHub, provides a unified command-line interface for interacting with GitHub. The gh secret family of commands was introduced to empower developers and CI/CD pipelines to manage GitHub Actions secrets directly from the terminal. This capability streamlines automation workflows, allowing for programmatic setup and rotation of sensitive credentials without needing to interact with the web UI. Its development paralleled the growing adoption and features of GitHub Actions, ensuring a robust CLI experience for managing workflow dependencies.

gh(1), gh secret list(1), gh secret delete(1), gh auth login(1)