GitHub Actions secrets

A key feature within GitHub Actions is the ability to use secrets to manage sensitive data like passwords, private keys, API tokens, and other credentials. In this guide, we'll explore the different aspects of managing secrets in GitHub Actions, including inheritance, safety, best practices, and more.

Understanding GitHub Actions secrets

Secrets in GitHub Actions are encrypted environment variables that you create in a repository, organization, or environment to store sensitive data. The encryption and limited exposure of secrets help maintain the security and privacy of your data throughout the automation process. Secrets are unique objects in GitHub as once they are created, they are immutable, encrypted, and redacted from console output and logs.

Creating secrets for a repository

To add a secret to a repository, follow these steps:

1. Navigate to your GitHub repository.
2. Go to Settings > Secrets > Actions. The URL for this page should be https://github.com/<REPO_OWNER>/<REPO_NAME/settings/secrets/actions
3. Click on New repository secret.
4. Name your secret and enter its value. The name should be in uppercase with underscores to separate words, like API_KEY.
5. Click Add secret.

This will securely save the secret and make it available to GitHub Actions workflows in that repository.

Creating secrets for a specific environment

If you are managing deployment workflows, you can define environment-specific secrets. Here’s how:

1. Go to your repository’s Settings > Environments. Located here: https://github.com/<REPO_OWNER>/<REPO_NAME/settings/environments
2. Click on the environment you want to configure, or create a new one by clicking New environment.
3. Under the Secrets section, click on Add secret.
4. Enter the name and value of the secret, then save it.

Environment secrets override repository secrets with the same name, allowing for more granular configurations.

Creating secrets for an organization

For secrets that are applicable across multiple repositories within an organization, you can create organization secrets:

1. Navigate to your organization's Settings.
2. Select Secrets > Actions.
3. Click on New organization secret.
4. Enter the name and value of the secret.
5. Specify the repositories that can access this secret or choose to make it available to all current and future repositories.

Organization secrets help maintain consistency and simplify management across multiple projects.

Best practices for GitHub Actions secrets

• Naming conventions: Use clear, descriptive names for your secrets. Consistent naming helps in identifying the type of secret and its purpose.
• Access control: Limit the exposure of secrets by controlling which repositories or environments can access them. Always follow the principle of least privilege.
• Rotation of secrets: Regularly rotate secrets to minimize the risk of exposure. Automate this process as much as possible to maintain security without sacrificing productivity.
• Avoid hardcoding secrets: Never hardcode secrets in your code or GitHub Actions workflows. Always use the secrets context or environment variables to reference secrets.

Using the REST API to manage GitHub Actions secrets

You can use GitHub's REST API to programmatically manage secrets. Here’s how you might add a new secret to a repository using the API:

1. Generate a personal access token with the appropriate permissions.
2. Use the token to authenticate your API requests.
3. Send a PUT request to the API endpoint to create or update a secret.

Here is an example using curl:

curl -X PUT -H "Authorization: token YOUR_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/<USERNAME>/<REPOSITORY_NAME>/actions/secrets/SECRET_NAME \
-d '{"encrypted_value":"ENCRYPTED_VALUE","key_id":"KEY_ID"}'

In this command:

• ENCRYPTED_VALUE is the encrypted value of your secret.
• KEY_ID is the identifier for the public key used to encrypt secret values, retrievable via the API.

For further reading on GitHub Actions secrets, see the official GitHub documentation.