Introduction

Reusable workflows do not automatically inherit every secret the way many teams first expect. A caller may have the secret, but the callee still cannot access it unless the workflow contract and the invocation both line up correctly. The result looks like a permission or runtime failure, but the real problem is usually that the secret was never part of the reusable workflow interface in the first place.

Symptoms

  • A called workflow reports that a required secret is missing
  • The same secret works in a normal workflow but not in a reusable one
  • Cross-repository reusable workflows fail while same-repository calls appear simpler
  • Teams assume secrets: inherit or similar behavior where the current setup does not actually provide it

Common Causes

  • The reusable workflow does not declare the secret under workflow_call.secrets
  • The caller passes the value in the wrong block or not at all
  • Repository or organization secret scope does not match the calling workflow context
  • Teams assume secrets are inherited automatically across workflow boundaries

Step-by-Step Fix

  1. 1.Declare required secrets in the reusable workflow contract
  2. 2.The callee must define what secrets it expects before callers can satisfy that contract.
yaml
on:
  workflow_call:
    secrets:
      deploy_key:
        required: true
  1. 1.Pass secrets explicitly from the caller
  2. 2.Keep the handoff explicit so the call site documents exactly what sensitive values are flowing into the reusable workflow.
yaml
jobs:
  deploy:
    uses: org/shared/.github/workflows/deploy.yml@main
    secrets:
      deploy_key: ${{ secrets.DEPLOY_KEY }}
  1. 1.Check repository and organization secret scope
  2. 2.A secret that exists in one repository or environment is not automatically available to another caller context.
  3. 3.Retest with a minimal secret-visibility check
  4. 4.A small diagnostic step can confirm whether the callee sees the secret before the real deploy logic runs.

Prevention

  • Treat reusable workflows as explicit interfaces, including their secret contract
  • Keep secret names consistent between caller and callee when possible
  • Document required secrets in the reusable workflow itself
  • Verify cross-repository secret behavior before depending on it in production automation