GitHub Actions/Security/Secrets, variables, permissions and OIDC

ConceptUpdated 3 weeks ago

Secrets, variables, permissions and OIDC

Where credentials live (repo, environment, org), least-privilege GITHUB_TOKEN permissions, and keyless cloud login with OIDC instead of long-lived keys.

#github-actions #secrets #oidc #security

Secrets and variables

Level	Scope	Use for
Organization	Selected / all repos	Shared keys (e.g. `DOTENV_PRIVATE_KEY`, registry tokens)
Repository	One repo	Repo-specific tokens
Environment	One job with `environment: production`	Prod-only secrets, protected by approval rules

secrets.X is encrypted and masked in logs. vars.X is plain config (region, URLs). Precedence: environment > repository > organization.

Set from the CLI

SHELL

1gh secret set DB_PASSWORD # prompts for value

2gh secret set AWS_ROLE_ARN --env production

3gh secret set DOTENV_PRIVATE_KEY --org my-org --visibility all

4gh variable set AWS_REGION --body eu-central-1

5gh secret list

GITHUB_TOKEN permissions

Every run gets an automatic GITHUB_TOKEN (${{ secrets.GITHUB_TOKEN }}), valid only for this repo and this run. Grant only what the job needs.

permissions block

YAML

1permissions: # workflow default: read-only

2 contents: read

4jobs:

5 publish:

6 permissions:

7 contents: write # create releases, push tags

8 packages: write # push images to ghcr.io

9 id-token: write # request an OIDC token for cloud login

10 pull-requests: write # comment on PRs

OIDC: no stored cloud keys

GitHub issues a short-lived signed token per run; AWS/GCP/Azure trust it and return temporary credentials. Nothing to rotate or leak.

STEP 1 OF 4

Cloud side: create an OIDC identity provider for token.actions.githubusercontent.com

AWS example

YAML

1permissions:

2 id-token: write

3 contents: read

4steps:

5 - uses: aws-actions/configure-aws-credentials@v6

6 with:

7 role-to-assume: ${{ vars.AWS_ROLE_ARN }}

8 aws-region: ${{ vars.AWS_REGION }}

9 - run: aws sts get-caller-identity # proves the login worked

Env files with dotenvx

Pattern: commit encrypted .env.production (dotenvx), keep only DOTENV_PRIVATE_KEY as an org secret, decrypt at runtime. One source of truth for all env vars.

Decrypt in CI

YAML

1- run: npx @dotenvx/dotenvx run -f .env.production -- npm run migrate

2 env:

3 DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}

Secrets are not passed to workflows triggered from forks, and are empty when misspelled (no error). Never echo a secret or write it to an artifact.

GitHub Actions/Security/Secrets, variables, permissions and OIDC

ConceptUpdated 3 weeks ago

Secrets, variables, permissions and OIDC

Where credentials live (repo, environment, org), least-privilege GITHUB_TOKEN permissions, and keyless cloud login with OIDC instead of long-lived keys.

#github-actions #secrets #oidc #security

Secrets and variables

Level	Scope	Use for
Organization	Selected / all repos	Shared keys (e.g. `DOTENV_PRIVATE_KEY`, registry tokens)
Repository	One repo	Repo-specific tokens
Environment	One job with `environment: production`	Prod-only secrets, protected by approval rules

secrets.X is encrypted and masked in logs. vars.X is plain config (region, URLs). Precedence: environment > repository > organization.

Set from the CLI

SHELL

1gh secret set DB_PASSWORD # prompts for value

2gh secret set AWS_ROLE_ARN --env production

3gh secret set DOTENV_PRIVATE_KEY --org my-org --visibility all

4gh variable set AWS_REGION --body eu-central-1

5gh secret list

GITHUB_TOKEN permissions

Every run gets an automatic GITHUB_TOKEN (${{ secrets.GITHUB_TOKEN }}), valid only for this repo and this run. Grant only what the job needs.

permissions block

YAML

1permissions: # workflow default: read-only

2 contents: read

4jobs:

5 publish:

6 permissions:

7 contents: write # create releases, push tags

8 packages: write # push images to ghcr.io

9 id-token: write # request an OIDC token for cloud login

10 pull-requests: write # comment on PRs

OIDC: no stored cloud keys

GitHub issues a short-lived signed token per run; AWS/GCP/Azure trust it and return temporary credentials. Nothing to rotate or leak.

STEP 1 OF 4

Cloud side: create an OIDC identity provider for token.actions.githubusercontent.com

AWS example

YAML

1permissions:

2 id-token: write

3 contents: read

4steps:

5 - uses: aws-actions/configure-aws-credentials@v6

6 with:

7 role-to-assume: ${{ vars.AWS_ROLE_ARN }}

8 aws-region: ${{ vars.AWS_REGION }}

9 - run: aws sts get-caller-identity # proves the login worked

Env files with dotenvx

Pattern: commit encrypted .env.production (dotenvx), keep only DOTENV_PRIVATE_KEY as an org secret, decrypt at runtime. One source of truth for all env vars.

Decrypt in CI

YAML

1- run: npx @dotenvx/dotenvx run -f .env.production -- npm run migrate

2 env:

3 DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}

Secrets are not passed to workflows triggered from forks, and are empty when misspelled (no error). Never echo a secret or write it to an artifact.