Add a secret
- Repository → Settings → Secrets and variables → Actions.
- New repository secret, name it (e.g.
DATABASE_URL), paste the value, Add secret. - 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
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 deployUse 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 }}
EOFThe 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
| Scope | Available to | Typical use | Limit |
|---|---|---|---|
| Repository | every workflow in the repo (not fork PRs) | CI credentials, test keys | 100 |
| Environment | jobs with environment: <name>, after protection rules pass | production deploy keys, live API keys | 100 per environment |
| Organisation | selected or all repositories | shared registry tokens, Slack webhooks | 1,000 |
| Dependabot | Dependabot-triggered runs only | private package registry tokens | separate 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 secretIf 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-siteAWS 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_targetworkflows 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_TOKENminimalpermissions: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.