GitHub Actions reusable workflow uses must be a valid pinned reference
A reusable workflow call must reference a workflow file with a ref. A bare path or missing @ref is rejected.
What this error means
The workflow is rejected because the uses: value for a called workflow is not a valid full reference with a ref.
The workflow is not valid. .github/workflows/ci.yml (Line: 7): Invalid value. Expected format {owner}/{repo}/.github/workflows/{filename}@{ref}Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Missing @ref
A called workflow must end with @ref (a branch, tag, or SHA). Omitting it fails validation.
Wrong path to the workflow file
The path must be the full .github/workflows/<file>.yml within the owner/repo.
How to fix it
Use the full reusable workflow reference
- Reference owner/repo/.github/workflows/file.yml@ref.
- For same-repo calls, use ./.github/workflows/file.yml.
jobs:
call:
uses: octo-org/repo/.github/workflows/build.yml@v1Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Pin reusable workflows to a tag or SHA for stability.
- Run actionlint to validate reusable workflow references.