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.
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:
- Open the repository on GitHub and go to Settings.
- In the Security section of the sidebar, select Secrets and variables, then Actions.
- Open the Secrets tab and click New repository secret.
- 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
- 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 sameenvmapping as the failing step. - Re-run the workflow and open the step log in the Actions tab.
- If it reports empty, check the trigger (fork, Dependabot, reusable workflow), then the secret name and scope.
- 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. - 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.