guide7 min readBy Aliniyaz Mamat · updated

GitHub Actions Secrets: Add, Use & Rotate (2026)

GitHub Actions secrets are encrypted values you add under Settings → Secrets and variables → Actions and read in a workflow with ${{ secrets.NAME }}. This guide covers adding them, the three scopes (repository, environment, organisation), masking, limits, writing a .env inside a job, and replacing cloud keys with OIDC.

Key takeaways

  • ✓Reference a secret as ${{ secrets.NAME }}, ideally through env: on the step that needs it, not the whole job.
  • ✓Values are write-only and masked as *** in logs, but derived values (base64, URL-encoded) are not masked unless you call ::add-mask::.
  • ✓Environment secrets plus required reviewers give production deploys an approval gate.
  • ✓Limits: 48 KB per secret, 100 per repository or environment, 1,000 per organisation.
  • ✓For AWS, GCP and Azure use OIDC instead of stored keys: short-lived tokens, nothing to rotate.

Add a secret

  1. Repository → Settings → Secrets and variables → Actions.
  2. New repository secret, name it (e.g. DATABASE_URL), paste the value, Add secret.
  3. The value can't be viewed again, only replaced.
# same with the GitHub CLI
gh secret set DATABASE_URL --body "postgres://…" --repo acme/app
gh secret set PRIVATE_KEY < private.pem              # from a file
gh secret set -f .env.ci                              # every KEY=value line of a file
gh secret set STRIPE_KEY --env production --body "sk_live_…"
gh secret list                                        # names only, never values

Names may contain letters, digits and underscores, must not start with a digit or with GITHUB_, and are case-insensitive. If the secret is a fresh random value, create it with the secret generator.

Use secrets in a workflow

.github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Migrate and deploy
        env:                                   # only this step sees the values
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          API_KEY: ${{ secrets.API_KEY }}
          APP_ENV: ${{ vars.APP_ENV }}           # non-secret: Actions variables
        run: npm run deploy

Use variables (vars.NAME) for non-secret settings: they are readable in the UI and not masked, which keeps logs useful. Secrets cannot be used directly in if: conditions; map them to an env: value first and test that.

Writing a .env file inside a job

      - name: Create .env for the test run
        run: |
          cat > .env <<EOF
          DATABASE_URL=${{ secrets.TEST_DATABASE_URL }}
          JWT_SECRET=${{ secrets.JWT_SECRET }}
          EOF

The file exists only on the runner and disappears with it. Don't upload it as an artifact, and don't cat it for debugging. To check which keys the tests expect, run your .env.example through the missing env detector.

Repository vs environment vs organisation secrets

ScopeAvailable toTypical useLimit
Repositoryevery workflow in the repo (not fork PRs)CI credentials, test keys100
Environmentjobs with environment: <name>, after protection rules passproduction deploy keys, live API keys100 per environment
Organisationselected or all repositoriesshared registry tokens, Slack webhooks1,000
DependabotDependabot-triggered runs onlyprivate package registry tokensseparate store
jobs:
  deploy-prod:
    runs-on: ubuntu-latest
    environment: production        # required reviewers / wait timer apply here
    steps:
      - run: ./deploy.sh
        env:
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}  # environment secret

If a repository and an environment secret have the same name, the environment secret wins for that job.

Masking: what it does and doesn't cover

  • Exact secret values are replaced with *** in logs.
  • Transformed values are not: base64, URL-encoded, JSON-escaped or a substring of the secret appear in clear text.
  • Mask derived values yourself: echo "::add-mask::$TOKEN" before using them.
  • Logs that already contain a secret are not cleaned up later. Delete the run and rotate the secret.

Use OIDC instead of long-lived cloud keys

permissions:
  id-token: write      # allow requesting the OIDC token
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy
          aws-region: eu-central-1
      - run: aws s3 sync ./dist s3://acme-site

AWS trusts GitHub's OIDC provider for this repository and branch and returns credentials valid for about an hour. There's no AWS_SECRET_ACCESS_KEY to store, leak or rotate. Google Cloud (workload identity federation) and Azure (federated credentials) work the same way.

Security rules for secrets in Actions

  • Never put secrets in workflow YAML; it is committed and forked with the repository.
  • Keep secrets away from untrusted code: fork PRs don't get secrets by default, and pull_request_target workflows must not check out and run PR code with secrets in scope.
  • Pin third-party actions to a commit SHA; a compromised action can read every secret its job sees.
  • Give GITHUB_TOKEN minimal permissions: per workflow.
  • Rotate a secret as soon as it appears in a log, an artifact or a fork.

The general rules for env files are in .env best practices. For Vercel-hosted apps, see Vercel environment variables.

Frequently asked questions

How do I use a GitHub secret in a workflow?

Map it into an environment variable on the step: env: { API_KEY: ${{ secrets.API_KEY }} }, then read $API_KEY in the script. Actions inputs work the same: with: { token: ${{ secrets.TOKEN }} }.

Can I read a secret's value after saving it?

No. Secrets are write-only in the UI and API. Keep the source of truth in your password manager or secrets manager.

Can Dependabot read my repository secrets?

No. Dependabot-triggered runs only get Dependabot secrets, configured separately under Settings → Secrets and variables → Dependabot.

Are secrets available in pull requests from forks?

No, not with the pull_request trigger. That protects you from malicious PRs; keep it that way and be careful with pull_request_target.

How big can a secret be?

Up to 48 KB. For larger files, encrypt the file in the repository and store only the passphrase as a secret, or fetch it from a secrets manager at runtime.

Related tools

Continue reading