Skip to content
Exlogare
← Back to all posts
by Exlogare Team GitHub Actions CI/CD reusable workflows troubleshooting

GitHub Actions reusable workflows: is the caller or workflow_call at fault?

How to debug reusable workflow failures in GitHub Actions: inputs, secrets, permissions, called workflow SHA, matrix cells, and job IDs without tab-hopping.

Reusable workflows in GitHub Actions are convenient: one shared workflow can be called from many repositories with workflow_call. But when it fails, the question becomes: did the caller repository break, or did the shared workflow break?

For junior and mid-level engineers, the hard part is that the evidence is spread across the caller workflow, called workflow, matrix job, and permissions settings.

Caller vs called workflow

The caller workflow is the workflow in your repository that invokes the shared file. The called workflow is the reusable workflow declared with on: workflow_call. It receives inputs, secrets, and permissions, but not always the way teams expect.

Common failure causes

1. Missing input. The called workflow marks an input as required, but the caller does not pass it.

2. Secrets are not inherited. secrets: inherit does not behave the same in every organization/repository setup.

3. Permissions are too narrow. The called workflow wants to write a check or comment, but the token only has read permissions.

4. Wrong workflow SHA. You think you are calling the latest version, but the caller is pinned to a tag or branch with older code.

5. Matrix hides the real scope. The reusable workflow failed in one matrix cell, not in every environment.

What to inspect

  • The uses: line in the caller workflow.
  • Inputs and secrets in the call block.
  • permissions: at workflow and job level.
  • github.workflow_ref and called workflow commit SHA.
  • The job ID and matrix values of the red cell.

Minimal example

jobs:
  test:
    uses: org/ci/.github/workflows/node-test.yml@v2
    with:
      node-version: "20"
    secrets: inherit
    permissions:
      contents: read
      checks: write

If the called workflow tries to create a PR comment, checks: write may not be enough. If v2 points to an old tag, the issue may already be fixed on main.

Where Exlogare fits

When a reusable workflow fails, the PR author should not have to jump caller → called → matrix cell → raw logs. Exlogare can receive the GitHub Actions log and post an RCA in the PR: where it failed, which workflow was involved, and what to check first. See GitHub Actions ingest.

Related reading

Checklist

  • Check uses: and the called workflow version.
  • Compare inputs with workflow_call.
  • Verify secrets and secrets: inherit.
  • Inspect effective permissions.
  • Find the specific matrix cell.
  • Put RCA in the PR so the author does not reconstruct context manually.