When a reusable workflow fails, check its boundaries in order: confirm the called file is in .github/workflows and declares workflow_call, verify the caller uses it at job level, then inspect inputs, secrets, access, token permissions, and environment-variable assumptions. These are separate contracts; a failure in any one can make a workflow appear not to recognize a secret or input.
First, confirm the workflow is callable
A reusable workflow must be a workflow file directly inside .github/workflows, and its on declaration must include workflow_call. GitHub does not support placing reusable workflows in subdirectories under .github/workflows. See GitHub’s Reuse workflows documentation.
As an Amazon Associate I earn from qualifying purchases.
For example, a called workflow can begin like this:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →name: Shared checks
on:
workflow_call:
inputs:
run_lint:
type: boolean
required: false
default: true
Check the file path and trigger before debugging what happens inside its jobs. A workflow without workflow_call is not exposed as a reusable workflow.
#1 Best Overall
Why can’t I add steps to a reusable workflow call job?
Reusable workflows are invoked directly by a job’s uses key, not from a step. GitHub Docs states: “Unlike when you are using actions within a workflow, you call reusable workflows directly within a job, and not from within job steps.” GitHub’s reuse guide explains the distinction.
A caller job therefore looks like this:
jobs:
shared_checks:
uses: ./.github/workflows/shared-checks.yml
Do not treat that job like an ordinary job with runs-on and steps surrounding the workflow call. If setup steps must happen before or after shared work, move them into the called workflow or arrange them in a separate job with the required dependency. A composite action is the alternative when the shared unit is a set of steps inside an existing job: it is used under steps, cannot contain jobs, and appears as a step in logs. A reusable workflow can contain jobs and exposes those jobs and their steps separately.
Does the input contract match?
Inputs are an explicit interface. Declare each input under on.workflow_call.inputs, specify its type, and pass its value through the caller job’s with. The caller’s value must match the declared type; pay particular attention to booleans and numbers rather than assuming every value is a string.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsjobs:
shared_checks:
uses: ./.github/workflows/shared-checks.yml
with:
run_lint: true
Compare the input names in both files character for character, and check whether each input is required or has a default. An undeclared input or a value of the wrong type violates the called workflow’s interface. The same GitHub guide documents the declaration and call syntax.
Why can’t my reusable workflow see a secret?
Secrets do not automatically cross from the caller into a reusable workflow. Map the required secret on the calling job, or use secrets: inherit when that is permitted and appropriate. If the called workflow calls another reusable workflow, it must pass the secret onward again; inheritance or mapping at one boundary does not make it available throughout the entire chain.
jobs:
deploy:
uses: ./.github/workflows/deploy.yml
secrets:
deploy_token: ${{ secrets.DEPLOY_TOKEN }}Check both sides of the contract: the called workflow must declare the secret under on.workflow_call.secrets, and the caller must provide the matching secret name. Also verify that the repository or organization secret exists and that the caller is allowed to access it. An unset secret reference evaluates to an empty string, which can look like a downstream authentication failure. Never print a secret value to diagnose this; check whether it is present without exposing it. See GitHub’s Using secrets in GitHub Actions guidance and the reusable workflow documentation.
Can the caller access every workflow in the chain?
The initial caller must be able to access each workflow it invokes. For a workflow in a private or internal repository, review the caller’s Actions settings and the called repository’s access policy. Repeat that check for each nested workflow: a working first call does not prove that every later repository is accessible. GitHub’s reference on reusable workflow configuration describes the access requirements.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Are token permissions sufficient?
A reusable workflow cannot raise GITHUB_TOKEN permissions above those it receives. Permissions in a nested chain can stay the same or become more restrictive, but not more permissive. If an operation fails with an authorization error, set the required permissions in the caller’s context and check what is passed to each called workflow. Do not assume a permission requested deeper in the chain can override a more restrictive caller. Consult GitHub’s configuration reference for the current rules.
Are workflow-level environment variables crossing the boundary?
Workflow-level env values do not propagate from the caller into a called workflow, and values set in the called workflow do not flow back through env. Use declared inputs for caller-provided values, shared vars where appropriate, or workflow outputs to return values. A variable that exists in one workflow’s environment should not be assumed to exist in another. GitHub documents this boundary in its reusable workflow configuration reference.
Is the caller job using supported keys?
A job that calls a reusable workflow has a restricted set of valid keys. It is not interchangeable with a normal job that owns its runner and steps. Compare the caller job against GitHub’s current supported-key list in the workflow configuration reference, rather than adding familiar job keys by habit.
Is the nested workflow chain valid?
GitHub documents a maximum of ten workflow levels, counting the top-level caller, and does not permit loops in the chain. Trace the calls from the entry workflow through every nested workflow to find accidental cycles or excess depth. Some limits and reference behavior can depend on the GitHub product version, so check the current reference for the product you use rather than treating product-specific conditions as universal. See the reuse guide and the configuration reference.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Is the workflow reference stable and correct?
For a workflow in another repository, confirm the repository, file path, and ref in the call. Pinning the reference to a commit SHA makes the target stable and is the recommended choice when reproducibility and security matter. A same-repository relative reference uses the caller’s commit. A valid reference still depends on the caller being permitted to access the target repository.
jobs:
shared_checks:
uses: organization/repository/.github/workflows/shared-checks.yml@<commit-sha>
Use the exact path and ref intended for the call, and verify that access policy permits it. GitHub’s Reuse workflows guide covers reference formats and pinning.
A practical order for debugging
- Confirm the file is directly under
.github/workflowsand declaresworkflow_call. - Confirm the caller uses the workflow under a job’s
uses, not insidesteps. - Match every declared input name and type to the caller’s
withvalues. - Verify each secret is declared, available to the caller, and passed at every workflow boundary.
- Check access to every called repository in the chain.
- Confirm the caller grants the token permissions needed for the operation.
- Replace assumptions about cross-workflow
envwith inputs,vars, or outputs. - Validate the caller job’s allowed keys and the chain’s depth and direction.
- For cross-repository calls, verify the exact path and ref and prefer a commit SHA for stability.
These checks isolate the most common documented boundary failures without assuming that every report of an invisible secret has the same cause. The exact bug implied by “the bug I fixed eleven times” cannot be identified from GitHub’s public documentation alone; the original failing YAML and verified fix would be needed to establish that particular incident.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
