GitHub Actions composite action "shell is required"

By Daniel Zoghalchali·Latchkey

In a composite action, every run step must declare shell explicitly - there is no default shell at the action level. Omitting it fails the action at load time.

What this error means

A composite action fails to run with a message that shell is required on a run step, even though the same run would default fine in a workflow job.

Error: Your workflow file was invalid: every step in a composite action with a 'run' must have a 'shell' keyword set

Common causes

run step without shell in composite

A composite action run step omitted shell, which is mandatory there unlike in workflow jobs.

Assumed workflow defaults apply

defaults.run.shell from a workflow does not carry into a composite action.

How to fix it

Add shell to every composite run step

1. Set shell: bash (or pwsh) on each run step in action.yml.
2. Do not rely on workflow-level defaults inside a composite action.
3. Keep the shell consistent across the action's steps.

runs:
  using: composite
  steps:
    - run: echo "hello"
      shell: bash

How to prevent it

• Always set shell on composite-action run steps.
• Remember composite actions do not inherit workflow run defaults.
• Validate composite action.yml with a linter.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions