gh-secret

List secret keys for the current repository

$ gh secret list

$ gh secret list [[-o|--org]] [organization]

$ gh secret list [[-R|--repo]] [owner]/[repository]

$ gh secret set [name]

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

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

$ gh secret remove [name]

$ gh secret remove [name] [[-o|--org]] [organization]

gh secret <subcommand> [<secret-name>] [options]

<secret-name>
    Specifies the name of the secret to manage. This argument is required for the set and delete subcommands.

--body, -b <string>
    The value of the secret to be set. If this option is not provided, the command will read the secret value from standard input (stdin). This flag is used exclusively with the set subcommand.

--env, -e <name>
    Scopes the secret to a specific environment within a repository. This option is used to manage environment-specific secrets and is applicable to the set, delete, and list subcommands.

--org, -o <name>
    Scopes the secret to an entire organization. Use this option to manage organization-wide secrets. Applicable to the set, delete, and list subcommands.

--repos, -r <list>
    A comma-separated list of repository names that an organization secret should be accessible to. This option is used exclusively with organization secrets and the set subcommand.

--visibility, -v <string>
    Sets the visibility of an organization secret. Accepted values are all (accessible to all repositories in the organization), private (accessible only to private repositories), or selected (accessible to specific repositories defined by --repos). Defaults to private if not specified. Used with the set subcommand for organization secrets.

--add-for-repositories
    Used with the set subcommand for organization secrets. This flag adds the repositories specified by --repos to an existing organization secret's access list, rather than replacing the list entirely.

--remove-from-repositories
    Used with the set subcommand for organization secrets. This flag removes the repositories specified by --repos from an existing organization secret's access list.

--app <string>
    Specifies the target application for the secret. Accepted values are actions (for GitHub Actions workflows) or codespaces (for GitHub Codespaces). Defaults to actions if not specified. Applicable to the set, delete, and list subcommands.

The gh secret command is an essential component of the GitHub CLI (gh) tool, designed for secure and programmatic management of sensitive information within GitHub repositories, organizations, and environments. It empowers users to set, retrieve a list of, and delete secrets primarily utilized by GitHub Actions workflows or Codespaces. This command significantly streamlines the integration of confidential data, such as API tokens, private keys, or credentials, into CI/CD pipelines without directly exposing them in code. It supports various scopes for secrets, including specific repositories, organization-wide, or even environment-specific secrets, thereby ensuring fine-grained access control and adherence to robust security best practices.

The gh secret command requires the GitHub CLI (gh) to be installed and authenticated to your GitHub account.
Secrets are securely stored by GitHub and, once set, their values cannot be directly retrieved (read back) using this command; only their names can be listed or the secrets deleted.
Users must possess appropriate permissions (e.g., admin or write access to a repository, or organization owner/admin roles) to manage secrets effectively within GitHub.

When setting secrets, it is strongly advised to avoid hardcoding sensitive values directly in shell scripts. Instead, use secure input methods such as piping data from stdin (e.g., echo "$MY_SECRET_VALUE" | gh secret set MY_SECRET) or leveraging environment variables to pass values to the --body option securely.

Familiarize yourself with the different scopes available for secrets: repository (default, for the current repo), environment (for specific environments within a repo), and organization (for secrets accessible across an organization). Choosing the correct scope is crucial for applying the appropriate level of access control and isolation for your sensitive data within your GitHub ecosystem.

Secrets managed by gh secret can be explicitly targeted for use by either GitHub Actions workflows or GitHub Codespaces. This distinction allows for the creation and management of separate sets of credentials tailored to the specific requirements and security contexts of each application, enhancing granular control over sensitive data.

The gh secret command is an integral part of the GitHub CLI, which saw its initial beta release in 2019 and achieved general availability in September 2020. With the escalating adoption of GitHub Actions and Codespaces, the capability for programmatic management of sensitive credentials became critically important for robust CI/CD pipelines. The gh secret command was specifically developed to meet this demand, providing a straightforward command-line interface for securely interacting with GitHub's comprehensive secrets management system. Its evolution has consistently prioritized user-friendliness and adherence to stringent security practices for handling confidential data, integrating secret operations directly into modern developer workflows and automation scripts.

gh(1), git(1), gpg(1)