GitHub Actions Secret Not Passed to Script: Causes and Fixes

Fix a GitHub Actions secret that arrives empty in your script: map it with env, then check forks, Dependabot, reusable workflows and secret names.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7
Reading time
4 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

A secret reaches your script only if the step maps it explicitly: set env: API_TOKEN: ${{ secrets.API_TOKEN }} on the step, job or workflow, and read $API_TOKEN in the script. If the variable is still empty, the cause is almost always one of four things: the secret name or scope is wrong, the run was triggered from a fork, the run was triggered by Dependabot, or the secret crosses a reusable workflow boundary.

Map the secret to an environment variable

GitHub Actions can only read a secret that the workflow explicitly references. Scripts do not see secrets automatically, so map each one with env. For a related walkthrough, see Fix ‘Resource not accessible by integration’ (403) in GitHub Actions.

name: Build and Deploy

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Run script with secret
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: ./scripts/deploy.sh

Scope env to the step that needs the secret. Setting it at the job level exposes it to every step, including third-party actions.

Pass the value through the environment, not as an argument. Command-line arguments can be visible to other users through ps and can be captured by security audit events.

#!/usr/bin/env bash
set -euo pipefail

if [ -z "${API_TOKEN:-}" ]; then
  echo "Error: API_TOKEN is not set" >&2
  exit 1
fi

curl -s -H "Authorization: Bearer ${API_TOKEN}" https://api.example.com/endpoint

The guard fails fast with a clear message instead of sending an empty bearer token. Make the script executable (chmod +x scripts/deploy.sh) and check it in, or the step fails before the script reads anything.

PowerShell

The mechanism is the same on pwsh. Read the value from $env:API_TOKEN.

      - name: Run PowerShell script
        shell: pwsh
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: ./scripts/Deploy.ps1
$ErrorActionPreference = 'Stop'

if (-not $env:API_TOKEN) {
    throw 'API_TOKEN is not set'
}

Invoke-RestMethod -Uri 'https://example.com/deploy' -Headers @{
    Authorization = "Bearer $env:API_TOKEN"
}

Check that the secret exists and is in scope

A misspelled name does not fail the workflow. ${{ secrets.API_TOKEN }} simply evaluates to an empty string, so compare the name in the workflow with the name in the settings, including case.

To create a repository secret in the UI:

  1. Open the repository on GitHub and go to Settings.
  2. In the Security section of the sidebar, select Secrets and variables, then Actions.
  3. Open the Secrets tab and click New repository secret.
  4. Enter the Name and the Secret value, then click Add secret.

With the GitHub CLI:

gh secret set API_TOKEN
gh secret set API_TOKEN < secret.txt
gh secret list

The first command prompts for the value, the second reads it from a file, and gh secret list confirms the name exists. Creating secrets requires write access on an organization repository, or collaborator status on a personal one.

Also check where the secret lives. Environment secrets are only available to jobs that declare that environment:. Organization secrets are only available to repositories allowed by the secret’s access policy, which you can review under Secrets and variables > Actions in the organization settings.

Fork pull requests

With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. This is a security boundary: a fork can change the code the workflow runs, so it must not receive your credentials.

The result is an empty variable, not a failure, so guard the step:

name: Script Verification

on:
  pull_request:
    branches:
      - main

jobs:
  run-script:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Execute script with secret
        if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
        env:
          DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}
        run: ./scripts/deploy.sh

The if skips the step for fork PRs, so the job does not fail on a missing credential. Pull requests from branches in the same repository still get the real value.

Using pull_request_target

pull_request_target runs in the context of the base branch and can read repository secrets, so it can serve fork PRs that need credentials. Treat it as dangerous: never check out and run the fork’s code in a job that has secrets.

name: Fork PR Check

on:
  pull_request_target:
    branches:
      - main

jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out base repository
        uses: actions/checkout@v7

      - name: Run script from the base branch
        env:
          DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}
        run: ./scripts/verify-internal.sh

The default checkout here is the base branch, so verify-internal.sh is your code. If you add ref: ${{ github.event.pull_request.head.sha }}, any contributor can rewrite that script and read the secret.

Dependabot pull requests

Standard repository secrets are not available to workflows triggered by Dependabot events. Add the secret separately under Settings > Secrets and variables > Dependabot, using the same name your workflow references.

name: Dependabot Build

on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Run script with Dependabot secret
        env:
          DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}
        run: ./scripts/build.sh

Keep a copy of the secret in both stores if the same workflow runs for humans and for Dependabot. Updating one does not update the other.

Reusable workflows

Secrets are not automatically passed to reusable workflows. The caller must pass them, and the called workflow must declare them.

# caller
jobs:
  call:
    uses: ./.github/workflows/deploy.yml
    secrets:
      API_TOKEN: ${{ secrets.API_TOKEN }}
# .github/workflows/deploy.yml
on:
  workflow_call:
    secrets:
      API_TOKEN:
        required: true

For a reusable workflow in the same organization or enterprise, secrets: inherit in the caller passes all of the caller’s secrets without listing them.

Mask derived values

GitHub redacts secrets printed to logs, but redaction is not guaranteed when a value is transformed, and the runner only redacts secrets used within the current job. Register values generated at runtime, such as session tokens or decoded credentials, with ::add-mask::. For a related walkthrough, see Pass Outputs Between GitHub Actions Jobs.

name: Mask Demo

on: push

jobs:
  mask-demo:
    runs-on: ubuntu-latest
    steps:
      - name: Register mask and print value
        env:
          SESSION_VALUE: example-session-value
        run: |
          echo "::add-mask::$SESSION_VALUE"
          echo "Value is: $SESSION_VALUE"

The runner replaces matches of the registered string with *** in output produced after the command runs. Masking does not cover files: a secret written to a file and uploaded with actions/upload-artifact is stored in plain text.

Verify the fix

  1. Add a temporary step that reports presence without printing the value: run: '[ -n "$API_TOKEN" ] && echo "API_TOKEN is set" || echo "API_TOKEN is empty"', with the same env mapping as the failing step.
  2. Re-run the workflow and open the step log in the Actions tab.
  3. If it reports empty, check the trigger (fork, Dependabot, reusable workflow), then the secret name and scope.
  4. If you use the guarded script above, a missing value shows up as Error: API_TOKEN is not set. A successful run no longer prints it.
  5. Remove the temporary step once the secret arrives.

Do not use echo "$API_TOKEN" to test. Masking hides exact matches, but any transformation, such as base64 encoding, can bypass it.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.