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 or repository. 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.
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 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 lower 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.
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.
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 (PAT), 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 user 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 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 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 organization-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 organization-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 organization-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 organization-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 the left sidebar, click Secrets.
-
The list of secrets includes any configured permissions and policies. For example:
-
For more details on the configured permissions for each secret, click Update.
Using encrypted secrets in a workflow
Note: With the exception of GITHUB_TOKEN
, secrets are not passed to the runner when a workflow is triggered from a forked repository.
To provide an action with a secret as an input or environment variable, you can use the secrets
context to access secrets you've created in your repository. For more information, see "Contexts" and "Workflow syntax for GitHub Actions."
steps:
- name: Hello world action
with: # Set the secret as an input
super_secret: ${{ secrets.SuperSecret }}
env: # Or as an environment variable
super_secret: ${{ secrets.SuperSecret }}
Avoid passing secrets between processes from the command line, whenever possible. Command-line processes may be visible to other users (using the ps
command) or captured by security audit events. To help protect secrets, consider using environment variables, STDIN
, or other mechanisms supported by the target process.
If you must pass secrets within a command line, then enclose them within the proper quoting rules. Secrets often contain special characters that may unintentionally affect your shell. To escape these special characters, use quoting with your environment variables. For example:
Example using Bash
steps:
- shell: bash
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "$SUPER_SECRET"
Example using PowerShell
steps:
- shell: pwsh
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "$env:SUPER_SECRET"
Example using Cmd.exe
steps:
- shell: cmd
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "%SUPER_SECRET%"
Limits for secrets
You can store up to 1,000 organization secrets and 100 repository secrets.
A workflow created in a repository can access the following number of secrets:
- All 100 repository secrets.
- If the repository is assigned access to more than 100 organization secrets, the workflow can only use the first 100 organization secrets (sorted alphabetically by secret name).
Secrets are limited to 64 KB in size. To use secrets that are larger than 64 KB, you can store encrypted secrets in your repository and save the decryption passphrase as a secret on GitHub. For example, you can use gpg
to encrypt your credentials locally before checking the file in to your repository on GitHub. For more information, see the "gpg manpage."
Warning: Be careful that your secrets do not get printed when your action runs. When using this workaround, GitHub does not redact secrets that are printed in logs.
-
Run the following command from your terminal to encrypt the
my_secret.json
file usinggpg
and the AES256 cipher algorithm.$ gpg --symmetric --cipher-algo AES256 my_secret.json
-
You will be prompted to enter a passphrase. Remember the passphrase, because you'll need to create a new secret on GitHub that uses the passphrase as the value.
-
Create a new secret that contains the passphrase. For example, create a new secret with the name
LARGE_SECRET_PASSPHRASE
and set the value of the secret to the passphrase you selected in the step above. -
Copy your encrypted file into your repository and commit it. In this example, the encrypted file is
my_secret.json.gpg
. -
Create a shell script to decrypt the password. Save this file as
decrypt_secret.sh
.#!/bin/sh # Decrypt the file mkdir $HOME/secrets # --batch to prevent interactive command # --yes to assume "yes" for questions gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \ --output $HOME/secrets/my_secret.json my_secret.json.gpg
-
Ensure your shell script is executable before checking it in to your repository.
$ chmod +x decrypt_secret.sh $ git add decrypt_secret.sh $ git commit -m "Add new decryption script" $ git push
-
From your workflow, use a
step
to call the shell script and decrypt the secret. To have a copy of your repository in the environment that your workflow runs in, you'll need to use theactions/checkout
action. Reference your shell script using therun
command relative to the root of your repository.name: Workflows with large secrets on: push jobs: my-job: name: My Job runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Decrypt large secret run: ./.github/scripts/decrypt_secret.sh env: LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }} # This command is just an example to show your secret being printed # Ensure you remove any print statements of your secrets. GitHub does # not hide secrets that use this workaround. - name: Test printing your secret (Remove this step in production) run: cat $HOME/secrets/my_secret.json
Storing Base64 binary blobs as secrets
You can use Base64 encoding to store small binary blobs as secrets. You can then reference the secret in your workflow and decode it for use on the runner. For the size limits, see "Limits for secrets".
Note: Note that Base64 only converts binary to text, and is not a substitute for actual encryption.
-
Use
base64
to encode your file into a Base64 string. For example:$ base64 -i cert.der -o cert.base64
-
Create a secret that contains the Base64 string. For example:
$ gh secret set CERTIFICATE_BASE64 < cert.base64 ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
-
To access the Base64 string from your runner, pipe the secret to
base64 --decode
. For example:name: Retrieve Base64 secret on: push: branches: [ octo-branch ] jobs: decode-secret: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Retrieve the secret and decode it to a file env: CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }} run: | echo $CERTIFICATE_BASE64 | base64 --decode > cert.der - name: Show certificate information run: | openssl x509 -in cert.der -inform DER -text -noout