prefer-file-extension

Rule catalog ID: R020

Targeted pattern scope

GitHub Actions workflow YAML files under .github/workflows/.

What this rule reports

This rule reports workflow files whose extension does not match the configured preference.

Why this rule exists

Using one workflow file extension consistently keeps repositories easier to scan, search, and script against. It also avoids needless churn from mixed .yml and .yaml naming styles.

❌ Incorrect

# .github/workflows/release.yaml
name: Release
on:
  workflow_dispatch:

✅ Correct

# .github/workflows/release.yml
name: Release
on:
  workflow_dispatch:

Behavior and migration notes

Default behavior

With the default configuration, this rule expects workflow files to use the .yml extension.

`{ "extension": "yaml" }`

Use this option to enforce .yaml instead.

`{ "caseSensitive": false }`

Use this option when you want extension matching to ignore case differences in repository paths.

Additional examples

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/prefer-file-extension": "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​

Behavior and migration notes​

Default behavior​

{ "extension": "yaml" }​

{ "caseSensitive": false }​

Additional examples​

ESLint flat config example​

When not to use it​

Further reading​