Introduction

Reusable workflows are validated before execution. If the caller passes the wrong type, omits a required field, or sends a secret through with instead of secrets, GitHub rejects the workflow call immediately. The failure looks like a runtime problem, but the job never truly starts because the interface contract between caller and reusable workflow is broken.

Symptoms

  • The reusable workflow fails before any steps execute
  • GitHub reports a missing required input or an invalid value
  • A workflow worked before a reusable template changed its inputs
  • Secrets appear to be passed, but the reusable workflow still fails validation

Common Causes

  • The caller does not provide a required workflow_call input
  • The caller passes a string for a boolean or number field
  • A choice-like convention is used informally, but the caller sends an unexpected value
  • A secret is incorrectly passed through with instead of the secrets block

Step-by-Step Fix

  1. 1.Inspect the reusable workflow contract
  2. 2.Start with the workflow_call definition on the exact ref the caller uses.
yaml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy_token:
        required: true
  1. 1.Match the caller to the declared input types
  2. 2.The caller must satisfy the reusable workflow interface exactly.
yaml
jobs:
  deploy:
    uses: org/repo/.github/workflows/deploy.yml@main
    with:
      environment: staging
    secrets:
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}
  1. 1.**Move secrets out of with**
  2. 2.Reusable workflow secrets belong under secrets, not in the normal input map.
  3. 3.Retest after interface changes
  4. 4.If the reusable workflow input schema changed, update every caller that consumes it, not just one template branch.

Prevention

  • Treat reusable workflows as versioned interfaces, not loose shared snippets
  • Keep required inputs minimal and well documented
  • Use defaults for optional inputs where practical
  • Update all callers when a reusable workflow changes its contract