require-run-step-shell

Rule catalog ID: R021

Targeted pattern scope

GitHub Actions workflow YAML files with run steps.

What this rule reports

This rule reports run steps that do not declare shell themselves and do not inherit one from defaults.run.shell. It also reports empty or non-string shell values when they are declared on a step or in defaults.

Why this rule exists

GitHub Actions uses different implicit shells depending on the runner and execution context. Making the shell explicit keeps inline scripts predictable, documents intent for reviewers, and avoids surprises such as sh behavior where authors expected bash or pwsh.

❌ Incorrect

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install
        run: npm ci

✅ Correct

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install
        shell: bash
        run: npm ci

Additional examples

defaults:
  run:
    shell: bash

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install
        run: npm ci

For larger repositories, this rule is often enabled together with one of the published presets so violations are caught in pull requests before workflow changes are merged.

ESLint flat config example

import githubActions from "eslint-plugin-github-actions-2";

export default [
  {
    files: ["**/*.{yml,yaml}"],
    plugins: {
      "github-actions": githubActions,
    },
    rules: {
      "github-actions/require-run-step-shell": "error",
    },
  },
];

When not to use it

You can disable this rule when its policy does not match your repository standards, or when equivalent enforcement is already handled by another policy tool.

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Additional examples​

ESLint flat config example​

When not to use it​

Further reading​