GitHub Actions cannot use needs in a reusable workflow input

By Daniel Zoghalchali·Latchkey

When calling a reusable workflow, the with inputs are evaluated in the caller. The needs context is available for that, but inside the called reusable workflow you cannot reference the caller’s needs - only the inputs context, so values must be passed in explicitly.

What this error means

A reusable workflow errors or reads empty because it references needs, which is not in scope inside the called workflow.

# inside the reusable workflow (.github/workflows/deploy.yml)
on:
  workflow_call:
    inputs:
      tag: { required: true, type: string }
jobs:
  go:
    steps:
      - run: echo "${{ needs.build.outputs.tag }}"   # needs not available here

Common causes

needs context is caller-scoped

The called workflow has its own job graph; it cannot see the caller’s needs.

Expecting upstream outputs without passing them

Outputs from the caller must be forwarded as inputs to the reusable workflow.

How to fix it

Pass the value as an input from the caller

1. In the caller, read needs.<job>.outputs and pass it via with.
2. Reference inputs.<name> inside the reusable workflow.

# caller
jobs:
  deploy:
    needs: build
    uses: ./.github/workflows/deploy.yml
    with:
      tag: ${{ needs.build.outputs.tag }}

Use inputs context inside the reusable workflow

1. Replace needs references with inputs.<name> in the called workflow.
2. Declare the input under on.workflow_call.inputs.

How to prevent it

• Treat reusable workflows as functions: pass everything via inputs.
• Do not rely on caller context (needs) inside the callee.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions