How to Fix GitHub Actions 'secret not found' Error

In this tutorial, you'll learn about How to Fix GitHub Actions 'secret not found' Error. We cover key concepts, practical examples, and best practices.

The Problem

Your GitHub Actions workflow fails with Error: secret not found or the secret resolves to an empty string. The workflow references ${{ secrets.MY_SECRET }} but the secret is not defined at the repository, environment, or organization level. GitHub Actions secrets are not available by default — you must create them explicitly.

Quick Fix

1. Add the secret to your repository

Go to: GitHub repository > Settings > Secrets and variables > Actions > New repository secret.

Enter the name and value exactly as used in your workflow. Secret names are case-sensitive.

2. Use secrets correctly in workflows

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
        run: |
          ./deploy.sh "$API_KEY" "$DB_PASSWORD"

3. Check if the secret exists

# Using GitHub CLI
gh secret list -R owner/repo

Expected output:

NAME         UPDATED
API_KEY      2024-01-15
DB_PASSWORD  2024-01-15

4. Use environment-level secrets

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # References the "production" environment
    steps:
      - run: ./deploy.sh
        env:
          API_KEY: ${{ secrets.API_KEY }}

Create the environment under Settings > Environments > production and add secrets there.

5. Debug secret availability (without exposing values)

- name: Verify secrets are set
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    if [ -z "$API_KEY" ]; then
      echo "API_KEY is empty or not found"
      exit 1
    fi
    echo "API_KEY is set (length: ${#API_KEY})"

6. Use organization secrets for shared access

Go to Organization Settings > Secrets and variables > Actions. Select which repositories can use each secret.

7. Pass secrets between jobs

jobs:
  build:
    outputs:
      deployment_url: ${{ steps.deploy.outputs.url }}
    steps:
      - id: deploy
        run: echo "url=https://example.com" >> $GITHUB_OUTPUT

Common Causes

Prevention

• Name secrets consistently: PROD_API_KEY, STAGING_API_KEY, DEV_API_KEY
• Use environment-level secrets for deployment-specific values
• Run gh secret list before troubleshooting to verify secrets exist
• Never print or log secret values — use ${#VAR} to check length