GitHub Action Secrets

GitHub provides encrypted secrets to allow you to store sensitive information like GitHub service account credentials for use with GitHub Actions.

Assess the Risk

Assess the risk of your secret based on type of access (read-only, append-only or write) and the sensitivity of what it grants access to (low or high risk).

• read-only : grants read-only permissions.
• append-only : grants permission to create but not update/delete. For example an access key to trigger a build, append to a log or send a message.
• write : grants permission to create, update and delete. For example a GitHub service account which can commit content changes.
• low-risk : grants access to a low risk system e.g. docs, dev or test infrastructure.
• high-risk : grants access to a high risk system e.g. any production data access.

Can you remove the need for a secret altogether? For example if authenticating to AWS (or any major cloud provider), prefer OpenID Connect to manage the workflow auth within AWS IAM directly rather than saving AWS access tokens in GitHub secrets.

Your Options

There are 3 places you can store your secret to make it available to your GitHub Action workflow:

Note the recommended use of repository environments to store write permission or high-risk system secrets.

Environment Secrets

A repository environment restricts secret access to a specific branch or team. Your secret is now protected by your branch protection rules. Setup your environment in repository Settings > Environments. Then target the environment you have configured in your workflow.

Example:

Your repository uses reviewed source: maintainers review changes in feature branches before merging to main. On merge to main a workflow builds and publishes a new release to GitHub Docker registry. You restrict publishing releases to a limited group to ensure changes are properly reviewed. This means you need to grant this workflow access to release via a GitHub access token. Since you only want reviewed and approved code published as a release, you add this access token in a repository environment that only the main branch can access. Therefore, only the main branch can publish new releases.

Repository Secrets

Add repository secrets in Settings > Secrets and variables > Actions. Code in any branch can access and use repository secrets in GitHub Action workflows. Any user with write access to the repository can create a branch and use the repository secret. This is convenient as the secret is available to pull request workflows, but be cautious especially if you grant write access to a general team like all-flutter-global.

Example:

You want to send a Slack message about a pull request. This requires a secret Slack webhook URL – an append-only secret. You store this secret as a repository secret and then write a workflow that uses it to publish a message about the pull request.

Organisation Secrets

The inner source team configure organisation secrets on your behalf. Org secrets provide the secret to many repositories. Within each repository it acts like a repository secret – available to all branches and users of that repository.

Example:

Many repositories use SonarCloud to scan feature branches for quality issues. To calculate metrics like test coverage, you run your tests in a GitHub Action workflow publish the results to SonarCloud. This requires SonarCloud credentials: an append-only secret to a low-risk system. These SonarCloud credentials are available to you in any repository as an org secret.