GitHub Actions uses with both ref and path is invalid

By Daniel Zoghalchali·Latchkey

A uses value is either a local path (./path, no @ref) or a remote reference (owner/repo@ref). Mixing them - a local path with an @ref - is not a valid action reference.

What this error means

The workflow fails to resolve the action, reporting an invalid uses value, after a local action path was written with an @ref suffix.

Invalid workflow file: ./.github/actions/build@v1
Local actions cannot specify a ref (use './.github/actions/build').

Common causes

Local path with @ref

Local actions are read from the checked-out commit; an @ref is meaningless and invalid.

Remote action missing @ref

Conversely, a remote owner/repo reference must include an @ref.

How to fix it

Use the correct uses form

1. For local actions: uses: ./.github/actions/build with no @ref.
2. For remote actions: uses: owner/repo@v1 (or a pinned SHA).
3. Checkout the repo before using a local action so the path exists.

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/build   # local, no ref

How to prevent it

• Pin remote actions to a SHA or tag; never add a ref to local paths.
• Run actionlint to catch malformed uses values.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions