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