Creating secrets for a repository

To create secrets or variables on GitHub for an organization repository, you must havewrite access. For a personal account repository, you must be a repository collaborator.

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Creating secrets for an environment

To create secrets or variables for an environment in a personal account repository, you must be the repository owner. To create secrets or variables for an environment in an organization repository, you must haveadmin access. For more information on environments, seeManaging environments for deployment.

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Creating secrets for an organization

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

Organization owners can create secrets or variables at the organization level.

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

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

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

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.

1. On GitHub, navigate to the main page of the organization.

2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then clickSettings.

   

3. In the "Security" section of the sidebar, select Secrets and variables, then clickActions.

4. The list of secrets includes any configured permissions and policies. For more details about the configured permissions for each secret, clickUpdate.

Using secrets in a workflow

To provide an action with a secret as an input or environment variable, you can use thesecrets context to access secrets you've created in your repository. For more information, seeContexts reference andWorkflow syntax for GitHub Actions.

steps:-name:Helloworldactionwith:# Set the secret as an inputsuper_secret:${{secrets.SuperSecret}}env:# Or as an environment variablesuper_secret:${{secrets.SuperSecret}}

Secrets cannot be directly referenced inif: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. For more information, seeContexts reference andjobs.<job_id>.steps[*].if.

If a secret has not been set, the return value of an expression referencing the secret (such as${{ secrets.SuperSecret }} in the example) will be an empty string.

Avoid passing secrets between processes from the command line, whenever possible. Command-line processes may be visible to other users (using theps command) or captured bysecurity 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:bashenv:SUPER_SECRET:${{secrets.SuperSecret}}run:|      example-command "$SUPER_SECRET"

Example using PowerShell

steps:-shell:pwshenv:SUPER_SECRET:${{secrets.SuperSecret}}run:|      example-command "$env:SUPER_SECRET"

Example using Cmd.exe

steps:-shell:cmdenv:SUPER_SECRET:${{secrets.SuperSecret}}run:|      example-command "%SUPER_SECRET%"

Storing large secrets

To use secrets that are larger than 48 KB, you can use a workaround to store secrets in your repository and save the decryption passphrase as a secret on GitHub. For example, you can usegpg to encrypt a file containing your secret locally before checking the encrypted file in to your repository on GitHub. For more information, see thegpg manpage.

1. Run the following command from your terminal to encrypt the file containing your secret usinggpg and the AES256 cipher algorithm. In this example,my_secret.json is the file containing the secret.

   gpg --symmetric --cipher-algo AES256 my_secret.json

2. 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.

3. Create a new secret that contains the passphrase. For example, create a new secret with the nameLARGE_SECRET_PASSPHRASE and set the value of the secret to the passphrase you used in the step above.

4. Copy your encrypted file to a path in your repository and commit it. In this example, the encrypted file ismy_secret.json.gpg.

   Warning

   Make sure to copy the encryptedmy_secret.json.gpg file ending with the.gpg file extension, andnot the unencryptedmy_secret.json file.

   git add my_secret.json.gpggit commit -m "Add new secret JSON file"

5. Create a shell script in your repository to decrypt the secret file. In this example, the script is nameddecrypt_secret.sh.

   Shell

   #!/bin/sh#Decrypt the filemkdir $HOME/secrets#--batch to prevent interactivecommand#--yes to assume"yes"for questionsgpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \--output $HOME/secrets/my_secret.json my_secret.json.gpg

6. Ensure your shell script is executable before checking it in to your repository.

   chmod +x decrypt_secret.shgit add decrypt_secret.shgit commit -m "Add new decryption script"git push

7. In your GitHub Actions workflow, use astep 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:Workflowswithlargesecretson:pushjobs:my-job:name:MyJobruns-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:Decryptlargesecretrun:./decrypt_secret.shenv: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:Testprintingyoursecret(Removethisstepinproduction)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, seeUsing secrets in GitHub Actions.

1. Usebase64 to encode your file into a Base64 string. For example:

   On macOS, you could run:

   base64 -i cert.der -o cert.base64

   On Linux, you could run:

   base64 -w 0 cert.der > cert.base64

2. Create a secret that contains the Base64 string. For example:

   $gh secretset CERTIFICATE_BASE64 < cert.base64✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo

3. To access the Base64 string from your runner, pipe the secret tobase64 --decode. For example:

   name:RetrieveBase64secreton:push:branches: [octo-branch ]jobs:decode-secret:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:Retrievethesecretanddecodeittoafileenv:CERTIFICATE_BASE64:${{secrets.CERTIFICATE_BASE64}}run:|          echo $CERTIFICATE_BASE64 | base64 --decode > cert.der-name:Showcertificateinformationrun:|          openssl x509 -in cert.der -inform DER -text -noout

Next steps

For reference information, seeSecrets reference.