Reusable Workflow Secrets Not Passed: Find the Handoff

Find the boundary where the secret disappears#

Treat “the secret is missing” as a boundary diagnosis, not as one generic permissions problem. Start with the earliest signal:

For the last case, the called workflow can test presence without exposing the credential:

1
jobs:
2
  deploy:
3
    runs-on: ubuntu-latest
4
    env:
5
      HAS_DEPLOY_TOKEN: ${{ secrets.deploy_token != '' }}
6
    steps:
7
      - name: Stop when the handoff is unavailable
8
        if: ${{ env.HAS_DEPLOY_TOKEN != 'true' }}
9
        run: echo '::error::deploy_token is unavailable in this workflow run'

This checks availability only. It does not make untrusted fork code safe to run with deployment credentials.

Declare the secret in the reusable workflow#

A reusable workflow is called through workflow_call. Named secrets make the contract visible and let GitHub validate the caller’s input:

1
name: Reusable deploy
2

3
on:
4
  workflow_call:
5
    inputs:
6
      environment:
7
        required: true
8
        type: string
9
    secrets:
10
      deploy_token:
11
        required: true
12

13
jobs:
14
  deploy:
15
    runs-on: ubuntu-latest
16
    steps:
17
      - uses: actions/checkout@v4
18
      - name: Deploy
19
        env:
20
          DEPLOY_TOKEN: ${{ secrets.deploy_token }}
21
          DEPLOY_ENVIRONMENT: ${{ inputs.environment }}
22
        run: ./scripts/deploy.sh "$DEPLOY_ENVIRONMENT"

The caller passes a named secret on the job that uses the reusable workflow:

1
jobs:
2
  deploy:
3
    uses: ./.github/workflows/reusable-deploy.yml
4
    with:
5
      environment: staging
6
    secrets:
7
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}

The uses form is a job-level call, so the reusable workflow’s inputs and secrets belong beside with, secrets, and uses, not inside a step. The caller and called workflow also need compatible permissions; a called workflow cannot elevate the permissions it receives.

Choose direct mapping or secrets: inherit#

Use direct mapping when the reusable workflow needs a small, documented set of secrets:

1
secrets:
2
  deploy_token: ${{ secrets.DEPLOY_TOKEN }}
3
  package_token: ${{ secrets.PACKAGE_TOKEN }}

Use secrets: inherit when the caller and reusable workflow are inside the same organization or enterprise boundary and passing the available repository, organization, or enterprise secrets is intentional:

1
jobs:
2
  deploy:
3
    uses: org/platform/.github/workflows/reusable-deploy.yml@main
4
    secrets: inherit

inherit is not a general cross-repository secret tunnel. For a reusable workflow outside the supported organization or enterprise boundary, map the required secrets explicitly or keep the secret-consuming job in the caller repository. Document the expected secret names even when using inherit; otherwise a rename can look like a permissions problem.

Forward secrets through nested reusable workflows#

Secrets do not automatically travel through a chain. If workflow A calls workflow B and B calls workflow C, A must pass a secret to B and B must pass it to C:

1
# A: caller
2
jobs:
3
  release:
4
    uses: ./.github/workflows/b.yml
5
    secrets:
6
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}
7

8
# B: reusable workflow calling C
9
jobs:
10
  publish:
11
    uses: ./.github/workflows/c.yml
12
    secrets:
13
      deploy_token: ${{ secrets.deploy_token }}

If B receives the secret but C does not, inspect the B-to-C edge first. The GitHub reusable workflow documentation also limits how far a nested chain can extend and requires secrets to be passed directly through each link.

Check environment-secret precedence#

Environment secrets are a common source of a misleading “missing secret” result. Secrets defined under an environment cannot be passed through on.workflow_call. If a job in the called workflow declares an environment, a secret with the same name from that environment takes precedence over the secret the caller attempted to pass.

Decide which boundary owns the credential:

• Use a workflow_call secret for a value supplied by the caller.
• Use an environment secret when deployment approval and environment protection should own the value.
• Do not give both boundaries the same name unless the precedence is deliberate and documented.

Debug the mapping without printing the value#

Check presence, not the secret itself. A temporary diagnostic step can expose whether the called workflow received a value while keeping the value masked:

1
- name: Check deploy token wiring
2
  env:
3
    DEPLOY_TOKEN: ${{ secrets.deploy_token }}
4
  run: |
5
    if [ -z "$DEPLOY_TOKEN" ]; then
6
      echo '::error::deploy_token was not passed to the reusable workflow'
7
      exit 1
8
    fi

Remove the diagnostic after fixing the contract. Never print a secret, its length, or a transformed version of it as a debugging shortcut.

A quick checklist#

1. The called file uses on.workflow_call and names the required inputs and secrets.
2. The caller maps each secret under the job-level secrets key, or intentionally uses secrets: inherit.
3. Every nested caller forwards the secret again.
4. No called job environment silently replaces the caller’s value.
5. The called workflow’s permissions are sufficient for the operation.
6. Diagnostics test presence without exposing the credential.

If the same caller also uses typed manual inputs, see how GitHub Actions handles boolean workflow-dispatch inputs. For a later artifact failure, check the hidden-file behavior of upload-artifact separately; it is a different boundary from secret passing.

FAQ#