error: invalid value workflow reference: references to workflows must use a ref that is a commit SHA, branch, or tag
ID: cicd/gha-reusable-workflow-ref
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| any | active | — | — | — |
Root Cause
Reusable workflow call fails because the 'uses' field references a workflow file with a dynamic expression, variable, or missing ref. GitHub requires reusable workflow references to be a static string with an explicit commit SHA, branch name, or tag -- expressions like ${{ vars.REF }} or ${{ github.event.inputs.branch }} are not allowed.
genericWorkarounds
-
95% success Pin the reusable workflow reference to a static branch, tag, or commit SHA
Change the uses field to a static reference: 'uses: org/repo/.github/workflows/reusable.yml@main' or 'uses: org/repo/.github/workflows/[email protected]' or 'uses: org/repo/.github/workflows/reusable.yml@abc123def'. Use tags for versioned releases and SHA for maximum reproducibility.
-
90% success Use workflow_call inputs to parameterize behavior within the reusable workflow instead of the ref
Keep the workflow ref static (e.g., @main) and use 'with:' inputs to pass configuration to the reusable workflow. Define 'on: workflow_call: inputs:' in the reusable workflow to accept parameters that control its behavior dynamically.
-
82% success Use repository_dispatch or workflow_dispatch with a wrapper workflow for dynamic version selection
Create a dispatcher workflow that uses the GitHub API (gh workflow run) to trigger the target workflow on a specific branch. The caller workflow makes an API call to dispatch the workflow on the desired ref, instead of using reusable workflow 'uses' syntax.
Dead Ends
Common approaches that don't work:
-
Use ${{ github.ref }} or other expressions as the ref in the reusable workflow 'uses' field
99% fail
GitHub Actions parses reusable workflow references at workflow compilation time, before any expressions are evaluated. The 'uses' field for reusable workflows does not support any form of dynamic expression -- it must be a literal string.
-
Use workflow_dispatch inputs to parameterize the reusable workflow ref
99% fail
Even though workflow_dispatch inputs are available at runtime, the reusable workflow 'uses' field is resolved statically during workflow parsing. Input values cannot be interpolated into the uses clause.
-
Use an environment variable or repository variable to specify the workflow version
99% fail
Neither env vars nor repository/organization variables can be used in the 'uses' field of a reusable workflow call. This is a fundamental limitation of how GitHub Actions resolves workflow dependencies at parse time.