What Are GitHub Secrets, and How Do You Use Them?

One of the challenges with any DevOps workflow is managing secrets, passwords, and tokens that must be kept private for security reasons. This is especially true for open source repositories, where code is typically public. GitHub Secrets help manage this issue when working with GitHub Actions scripts.

What Are GitHub Secrets?

GitHub Secrets is essentially a vault that you can store private keys in, which can be accessed by GitHub Actions scripts by name, much like environment variables. This solves the issue of keeping it in plaintext in the codebase, which is a massive security issue even for private repositories, and impossible for public ones without getting hacked immediately.

This is useful in many instances where the code may be public, but the Actions script needs to authenticate with some third party service. For example, if you host binaries on Amazon S3 buckets, you will need to give the script the access token to write to AWS storage. Of course, you don’t want to give anyone viewing the repository permission to overwrite the bucket contents. Using a secret restricts access, and also protects the key from being accidentally leaked.

• Repository secrets apply to a single repository. You’ll need to set them from the repository settings panel, which then be accessed like environment variables in GitHub Actions builds.
• GitHub Organizations secrets will apply to all repositories inside that organization, providing an easy way to centrally manage keys. They’re set from the organization settings.
• Environment secrets apply to specific GitHub Environments within the repo, like develop and production. This provides an easy way to override repository/organization secrets for different builds, such as deploying to a test environment vs. a production environment.

Currently, there’s no way to set user-specific secrets. If you want that functionality, consider making a personal organization.

You can store up to 1,000 organization secrets, 100 repository secrets, and 100 environment secrets. Secrets are also limited to 64Kb in size, though there are workarounds to this limitation. You can also store binary data as Base64 encoded strings.

It’s still possible to leak them from the Actions script if you, for example, printed them to the console with a command like echo. You’ll want to make sure none of the scripts you’re feeding the secrets into read it back to the user or output to any log files. Fortunately, GitHub does block the secret from being fed to certain logging commands, including echo.

Using GitHub Secrets

To set a repository-wide secret, you’ll need to head to the settings panel for the repository, and click Secrets > Actions. You can also set secrets for GitHub Codespaces, and Dependabot, if you use those.

You can set a variable name, and paste in the secret content. Once you leave this window though, you won’t be able to see the key again, though you can edit it and paste in a new key. This is generally how most secret stores should work, and is a good security feature, but don’t expect to be able to see this key again.

The naming convention for secret names is uppercase with underscores, otherwise known as “screaming snake case,” but this isn’t enforced by anything.

Then, in your Actions script, you can reference it by escaping it as a YAML variable, like so:

${{ secrets.SECRET_NAME }}

Note that “secrets.” context must be included before the secret name. You also don’t need to do anything special to reference organization secrets vs. single-repository ones.

This value can be passed to commands, but you can also use it to set environment variables for a process. This is typically how most tools will accept secrets anyway, since it’s the most secure and flexible system.

If a secret doesn’t exist in your account, GitHub will use an empty string as the value.

Organization Secrets

Setting organization-wide secrets is done the same way, however there are some additional controls over access and distribution.

When creating an organization secret, you can choose to have it only apply to public or private repositories, though private secrets for organization are a paid option. You can also select individual repositories.

To create or edit an organization secret, you must have “admin” access to the organization itself. This can be given to all members by editing the base permissions, but generally isn’t advised for big organizations.