Encrypted secrets

Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

About encrypted secrets

Secrets are encrypted environment variables that you create in an organization, repository, or repository environment. The secrets that you create are available to use in GitHub Actions workflows. GitHub uses a libsodium sealed box to help ensure that secrets are encrypted before they reach GitHub and remain encrypted until you use them in a workflow.

For secrets stored at the organization-level, you can use access policies to control which repositories can use organization secrets. Organization-level secrets let you share secrets between multiple repositories, which reduces the need for creating duplicate secrets. Updating an organization secret in one location also ensures that the change takes effect in all repository workflows that use that secret.

For secrets stored at the environment level, you can enable required reviewers to control access to the secrets. A workflow job cannot access environment secrets until approval is granted by required approvers.

Naming your secrets

The following rules apply to secret names:

Secret names can only contain alphanumeric characters ([a-z], [A-Z], [0-9]) or underscores (_). Spaces are not allowed.
Secret names must not start with the GITHUB_ prefix.
Secret names must not start with a number.
Secret names are not case-sensitive.
Secret names must be unique at the level they are created at.

For example, a secret created at the environment level must have a unique name in that environment, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.

If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence. Similarly, if an organization, repository, and environment all have a secret with the same name, the environment-level secret takes precedence.

To help ensure that GitHub redacts your secret in logs, avoid using structured data as the values of secrets. For example, avoid creating secrets that contain JSON or encoded Git blobs.

Accessing your secrets

To make a secret available to an action, you must set the secret as an input or environment variable in the workflow file. Review the action's README file to learn about which inputs and environment variables the action expects. For more information, see "Workflow syntax for GitHub Actions."

You can use and read encrypted secrets in a workflow file if you have access to edit the file. For more information, see "Access permissions on GitHub."

Warning: GitHub automatically redacts secrets printed to the log, but you should avoid printing secrets to the log intentionally.

Organization and repository secrets are read when a workflow run is queued, and environment secrets are read when a job referencing the environment starts.

You can also manage secrets using the REST API. For more information, see "Secrets."

Limiting credential permissions

When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use deploy keys or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating a personal access token, select the fewest scopes necessary.

Note: You can use the REST API to manage secrets. For more information, see "GitHub Actions secrets API."

Creating encrypted secrets for a repository

To create secrets for a personal account repository, you must be the repository owner. To create secrets for an organization repository, you must have admin access.

On your GitHub Enterprise Server instance, navigate to the main page of the repository.
Under your repository name, click Settings.
In the left sidebar, click Secrets.
Click New repository secret.
Type a name for your secret in the Name input box.
Enter the value for your secret.
Click Add secret.

If your repository has environment secrets or can access secrets from the parent organization, then those secrets are also listed on this page.

To learn more about GitHub CLI, see "About GitHub CLI."

To add a repository secret, use the gh secret set subcommand. Replace secret-name with the name of your secret.

gh secret set SECRET_NAME

The CLI will prompt you to enter a secret value. Alternatively, you can read the value of the secret from a file.

gh secret set SECRET_NAME < secret.txt

To list all secrets for the repository, use the gh secret list subcommand.

Creating encrypted secrets for an environment

To create secrets for an environment in a personal account repository, you must be the repository owner. To create secrets for an environment in an organization repository, you must have admin access.

On your GitHub Enterprise Server instance, navigate to the main page of the repository.
Under your repository name, click Settings.
In the left sidebar, click Environments.
Click on the environment that you want to add a secret to.
Under Environment secrets, click Add secret.
Type a name for your secret in the Name input box.
Enter the value for your secret.
Click Add secret.

To add a secret for an environment, use the gh secret set subcommand with the --env or -e flag followed by the environment name.

gh secret set --env ENV_NAME SECRET_NAME

To list all secrets for an environment, use the gh secret list subcommand with the --env or -e flag followed by the environment name.

gh secret list --env ENV_NAME

Creating encrypted secrets for an organization

When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.

To create secrets at the organization level, you must have admin access.

On your GitHub Enterprise Server instance, navigate to the main page of the organization.
Under your organization name, click Settings.

In the left sidebar, click Secrets.
Click New organization secret.
Type a name for your secret in the Name input box.
Enter the Value for your secret.
From the Repository access dropdown list, choose an access policy.
Click Add secret.

Note: By default, GitHub CLI authenticates with the repo and read:org scopes. To manage organization secrets, you must additionally authorize the admin:org scope.

gh auth login --scopes "admin:org"

To add a secret for an organization, use the gh secret set subcommand with the --org or -o flag followed by the organization name.

gh secret set --org ORG_NAME SECRET_NAME

By default, the secret is only available to private repositories. To specify that the secret should be available to all repositories within the organization, use the --visibility or -v flag.

gh secret set --org ORG_NAME SECRET_NAME --visibility all

To specify that the secret should be available to selected repositories within the organization, use the --repos or -r flag.

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2"

To list all secrets for an organization, use the gh secret list subcommand with the --org or -o flag followed by the organization name.

gh secret list --org ORG_NAME

Reviewing access to organization-level secrets

You can check which access policies are being applied to a secret in your organization.

On your GitHub Enterprise Server instance, navigate to the main page of the organization.
Under your organization name, click Settings.

In this article