Difference between Github's "Environment" and "Repository" secrets?

Question

In the GitHub documentation it states that the precedence of secrets is from lowest to highest (Environment > Repository > Organization), it also states that the Organization secrets are available for all repositories in the organization. But it doesn't state anything about Environment and Repository secrets.

My questions are:

1. What is the difference is between Environment and Repository secrets?
2. When should I use Environment secrets?
3. When should I use Repository secrets?

Answer 1

Well, environment secrets are specific to an environment in Github Actions which allow you to run different configurations for jobs in a single repository, e.g. to deploy to staging first and later to production.

Repository secrets are specific to a single repository (and all environments used in there), while organisation secrets are specific to an entire organisation and all repositories under it.

You can use environment secrets if you have secrets which are specific to an environment.

If you are unsure, you could also start with repository secrets for everything. If you later introduce different environments which require different secrets, you can move the repository secrets to the specific environments. Due to the inheritance chain, this should be transparent to the jobs.

Answer 2

To add to Holger Just's answer with an example workflow. The GitHub docs show an example when using the jobs.<job_id>.environment option in a workflow, but I think this is a more appropriate example.

name: Some task

on:
  push:
    branches:
      - main

jobs:
  prod-task:
    runs-on: ubuntu-latest
    environment: production
    steps:
      # uses production enviroment secrets over repository secrets
      - name: Run node build process
        run: "NODE_ENV=${{ env.NODE_ENV }} npm run build"
  dev-task:
    runs-on: ubuntu-latest
    environment: development
    steps:
      # uses development enviroment secrets over repository secrets
      - name: Run node build process
        run: "NODE_ENV=${{ env.NODE_ENV }} npm run build"
  task:
    runs-on: ubuntu-latest
    steps:
      # uses repository secrets as no environment is defined
      - name: Run node build process
        run: "NODE_ENV=${{ env.NODE_ENV }} npm run build"

Note: In the example above you can see the script accessing the environment variables via the env context using expressions.

So the idea is that when an environment is specified for a job, any secret used within that job, will use any environment-specific secret before using the repository secret.

To set an environment secret, navigate to the repo settings under the Environments section (i.e. https://github.com/<owner>/<repo>/settings/environments). Create or select an environment. Then add any secrets you need, see screenshot below. Make sure to provide the secret across all required environments which are to access it, otherwise the value will be inherited from parent env scope or possibly return ''.

Answer 3

The main reason I use environment secrets is that you can configure environments so that actions can only be run in them from protected branches. This allows me to have secrets in those environments that allow production deployment, but non-protected branches (e.g. an unreviewed PR) can't access those secrets even if they modify the workflow file.

So to recap, I have the following uses of each level of secret:

• organization: secrets that are relevant to most or all repos, and should be accessible from any PR, e.g. credentials that run general CI infrastructure that's the same for many repos,
• repo: secrets only relevant to one project, that can be accessed from any PR on that project, e.g. credentials that allow one specific niche kind of CI,
• environment: secrets that should not be available except to reviewed, merged PRs, e.g. credentials that allow deployment.

Unfortunately, there's no concept of an "organization environment", so the environment secrets have to be set up individually for each relevant repository. I do this with a script accessing the REST API.