GitHub Actions defaults.run.shell is ignored inside a composite action

By Kaveh Alemi·Latchkey

defaults.run.shell is a workflow/job setting. A composite action does not honor it: every run step in a composite action must specify its own shell, or the action fails to parse.

What this error means

A composite action errors that shell is required on a run step even though defaults.run.shell was set in the calling workflow.

Error: Required property is missing: shell
A composite action run step must explicitly set 'shell'.

Common causes

defaults does not propagate into actions

Job-level defaults apply to the job’s own steps, not to steps defined inside a composite action.

Run step missing an explicit shell

Composite run steps mandate a shell value with no inherited default.

How to fix it

Set shell on every composite run step

1. Add a shell value to each run step inside the composite action.
2. Use bash, pwsh, sh, etc. as appropriate.

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

Standardize on one shell across the action

1. Pick a single shell for the action and apply it consistently.
2. Document the shell requirement for maintainers.

How to prevent it

• Always set shell explicitly on composite run steps.
• Do not rely on workflow defaults inside actions.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions