eslint-plugin-github-actions-2 1.0.0

package/docs/rules/presets/strict.md

@@ -0,0 +1,48 @@
+# `githubActions.configs.strict`
+
+Opinionated operational guardrails for mature workflow estates.
+
+## Included rules
+
+- [`require-workflow-permissions`](../require-workflow-permissions.md)
+- [`require-job-timeout-minutes`](../require-job-timeout-minutes.md)
+- [`pin-action-shas`](../pin-action-shas.md)
+- [`require-workflow-concurrency`](../require-workflow-concurrency.md)
+- [`action-name-casing`](../action-name-casing.md)
+- [`job-id-casing`](../job-id-casing.md)
+- [`max-jobs-per-action`](../max-jobs-per-action.md)
+- [`no-external-job`](../no-external-job.md)
+- [`no-inherit-secrets`](../no-inherit-secrets.md)
+- [`no-invalid-concurrency-context`](../no-invalid-concurrency-context.md)
+- [`no-invalid-key`](../no-invalid-key.md)
+- [`no-invalid-reusable-workflow-job-key`](../no-invalid-reusable-workflow-job-key.md)
+- [`no-invalid-workflow-call-output-value`](../no-invalid-workflow-call-output-value.md)
+- [`no-pr-head-checkout-in-pull-request-target`](../no-pr-head-checkout-in-pull-request-target.md)
+- [`no-secrets-in-if`](../no-secrets-in-if.md)
+- [`no-self-hosted-runner-on-fork-pr-events`](../no-self-hosted-runner-on-fork-pr-events.md)
+- [`no-template-placeholder-in-non-template-workflow`](../no-template-placeholder-in-non-template-workflow.md)
+- [`no-top-level-env`](../no-top-level-env.md)
+- [`no-unknown-job-output-reference`](../no-unknown-job-output-reference.md)
+- [`no-unknown-step-reference`](../no-unknown-step-reference.md)
+- [`no-untrusted-input-in-run`](../no-untrusted-input-in-run.md)
+- [`no-write-all-permissions`](../no-write-all-permissions.md)
+- [`prefer-fail-fast`](../prefer-fail-fast.md)
+- [`prefer-file-extension`](../prefer-file-extension.md)
+- [`prefer-inputs-context`](../prefer-inputs-context.md)
+- [`require-action-name`](../require-action-name.md)
+- [`require-action-run-name`](../require-action-run-name.md)
+- [`require-checkout-before-local-action`](../require-checkout-before-local-action.md)
+- [`require-job-name`](../require-job-name.md)
+- [`require-job-step-name`](../require-job-step-name.md)
+- [`require-merge-group-trigger`](../require-merge-group-trigger.md)
+- [`require-pull-request-target-branches`](../require-pull-request-target-branches.md)
+- [`require-run-step-shell`](../require-run-step-shell.md)
+- [`require-trigger-types`](../require-trigger-types.md)
+- [`require-workflow-call-input-type`](../require-workflow-call-input-type.md)
+- [`require-workflow-call-output-value`](../require-workflow-call-output-value.md)
+- [`require-workflow-dispatch-input-type`](../require-workflow-dispatch-input-type.md)
+- [`require-workflow-interface-description`](../require-workflow-interface-description.md)
+- [`require-workflow-run-branches`](../require-workflow-run-branches.md)
+- [`valid-timeout-minutes`](../valid-timeout-minutes.md)
+- [`valid-trigger-events`](../valid-trigger-events.md)
+

package/docs/rules/presets/workflow-template-properties.md

@@ -0,0 +1,18 @@
+# `githubActions.configs.workflowTemplateProperties`
+
+Linting defaults for workflow-template metadata files (`*.properties.json`).
+
+## Included rules
+
+- [`no-empty-template-file-pattern`](../no-empty-template-file-pattern.md)
+- [`no-icon-file-extension-in-template-icon-name`](../no-icon-file-extension-in-template-icon-name.md)
+- [`no-invalid-template-file-pattern-regex`](../no-invalid-template-file-pattern-regex.md)
+- [`no-path-separators-in-template-icon-name`](../no-path-separators-in-template-icon-name.md)
+- [`no-subdirectory-template-file-pattern`](../no-subdirectory-template-file-pattern.md)
+- [`no-universal-template-file-pattern`](../no-universal-template-file-pattern.md)
+- [`require-template-categories`](../require-template-categories.md)
+- [`require-template-file-patterns`](../require-template-file-patterns.md)
+- [`require-template-icon-file-exists`](../require-template-icon-file-exists.md)
+- [`require-template-icon-name`](../require-template-icon-name.md)
+- [`require-workflow-template-properties-pair`](../require-workflow-template-properties-pair.md)
+

package/docs/rules/presets/workflow-templates.md

@@ -0,0 +1,22 @@
+# `githubActions.configs.workflowTemplates`
+
+Workflow template package linting for both template YAML and metadata files.
+
+## Included rules
+
+- [`no-empty-template-file-pattern`](../no-empty-template-file-pattern.md)
+- [`no-hardcoded-default-branch-in-template`](../no-hardcoded-default-branch-in-template.md)
+- [`no-icon-file-extension-in-template-icon-name`](../no-icon-file-extension-in-template-icon-name.md)
+- [`no-invalid-template-file-pattern-regex`](../no-invalid-template-file-pattern-regex.md)
+- [`no-path-separators-in-template-icon-name`](../no-path-separators-in-template-icon-name.md)
+- [`no-subdirectory-template-file-pattern`](../no-subdirectory-template-file-pattern.md)
+- [`no-universal-template-file-pattern`](../no-universal-template-file-pattern.md)
+- [`prefer-template-yml-extension`](../prefer-template-yml-extension.md)
+- [`require-template-categories`](../require-template-categories.md)
+- [`require-template-file-patterns`](../require-template-file-patterns.md)
+- [`require-template-icon-file-exists`](../require-template-icon-file-exists.md)
+- [`require-template-icon-name`](../require-template-icon-name.md)
+- [`require-template-workflow-name`](../require-template-workflow-name.md)
+- [`require-workflow-template-pair`](../require-workflow-template-pair.md)
+- [`require-workflow-template-properties-pair`](../require-workflow-template-properties-pair.md)
+

package/docs/rules/require-action-name.md

@@ -0,0 +1,61 @@
+# require-action-name
+
+> **Rule catalog ID:** R005
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files.
+
+## What this rule reports
+
+This rule reports workflows that omit the top-level `name` field or set it to a non-string or empty value.
+
+## Why this rule exists
+
+A workflow name is what most people see first in the Actions UI, run history, and status checks. Requiring it improves discoverability and reviewability.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+```
+
+## ✅ Correct
+
+```yaml
+name: CI
+on:
+  push:
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-action-name": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#name](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#name)
+- [https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs)

package/docs/rules/require-action-run-name.md

@@ -0,0 +1,63 @@
+# require-action-run-name
+
+> **Rule catalog ID:** R006
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files.
+
+## What this rule reports
+
+This rule reports workflows that omit the top-level `run-name` field or set it to a non-string or empty value.
+
+## Why this rule exists
+
+A descriptive `run-name` helps distinguish workflow runs triggered from different branches, releases, or manual dispatches.
+
+## ❌ Incorrect
+
+```yaml
+name: Release
+on:
+  workflow_dispatch:
+```
+
+## ✅ Correct
+
+```yaml
+name: Release
+run-name: Release ${{ github.ref_name }}
+on:
+  workflow_dispatch:
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-action-run-name": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#run-name](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#run-name)
+- [https://docs.github.com/actions/using-workflows/manually-running-a-workflow](https://docs.github.com/actions/using-workflows/manually-running-a-workflow)

package/docs/rules/require-checkout-before-local-action.md

@@ -0,0 +1,66 @@
+# require-checkout-before-local-action
+
+> **Rule catalog ID:** R025
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that use repository-local step actions with `uses: ./...`.
+
+## What this rule reports
+
+This rule reports step-level local action references that appear before any `actions/checkout` step in the same job.
+
+## Why this rule exists
+
+GitHub's workflow syntax requires checking out the repository before using a local action path. Without that checkout step, the action directory does not exist in the workspace and the workflow will fail at runtime.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/setup-project
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ./.github/actions/setup-project
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-checkout-before-local-action": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsuses](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsuses)

package/docs/rules/require-composite-step-name.md

@@ -0,0 +1,66 @@
+# require-composite-step-name
+
+> **Rule catalog ID:** R052
+
+## Targeted pattern scope
+
+Composite action `runs.steps` entries.
+
+## What this rule reports
+
+Reports composite steps missing a non-empty `name`.
+
+## Why this rule exists
+
+Named steps make action logs readable and troubleshooting faster.
+
+## ❌ Incorrect
+
+```yaml
+runs:
+  using: composite
+  steps:
+    - run: echo hello
+      shell: bash
+```
+
+## ✅ Correct
+
+```yaml
+runs:
+  using: composite
+  steps:
+    - name: Print greeting
+      run: echo hello
+      shell: bash
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-composite-step-name": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#runs-for-composite-actions](https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#runs-for-composite-actions)

package/docs/rules/require-job-name.md

@@ -0,0 +1,63 @@
+# require-job-name
+
+> **Rule catalog ID:** R007
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare jobs.
+
+## What this rule reports
+
+This rule reports jobs that omit `name` or set `name` to a non-string or empty value.
+
+## Why this rule exists
+
+Job names appear in workflow graphs and logs. Requiring them makes complex workflows easier to navigate, especially when job IDs are terse.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-job-name": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
+- [https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow](https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow)

package/docs/rules/require-job-step-name.md

@@ -0,0 +1,69 @@
+# require-job-step-name
+
+> **Rule catalog ID:** R008
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare explicit job steps.
+
+## What this rule reports
+
+This rule reports steps that omit `name` or set `name` to a non-string or empty value.
+
+## Why this rule exists
+
+Step names make job logs readable and help reviewers understand the intent of a step without reading the shell command or action source.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run tests
+        run: npm test
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-job-step-name": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps)
+- [https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs)

package/docs/rules/require-job-timeout-minutes.md

@@ -0,0 +1,76 @@
+# require-job-timeout-minutes
+
+> **Rule catalog ID:** R002
+
+## Targeted pattern scope
+
+Non-reusable workflow jobs under `jobs.<job_id>`.
+
+## What this rule reports
+
+This rule reports jobs that do not define `timeout-minutes`, jobs that use a non-integer timeout, and jobs that exceed the configured `maxMinutes` threshold.
+
+## Why this rule exists
+
+Explicit job timeouts make runner usage more predictable and reduce the blast radius of stuck processes or hanging external services.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+```
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+```
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: ${{ fromJson(vars.CI_TIMEOUT_MINUTES) }}
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-job-timeout-minutes": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idtimeout-minutes](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idtimeout-minutes)

package/docs/rules/require-merge-group-trigger.md

@@ -0,0 +1,67 @@
+# require-merge-group-trigger
+
+> **Rule catalog ID:** R035
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that validate pull requests with the `pull_request` trigger.
+
+## What this rule reports
+
+This rule reports workflows that subscribe to `pull_request` but do not also declare a `merge_group` trigger.
+
+## Why this rule exists
+
+GitHub documents that repositories using required GitHub Actions checks with merge queues must add the separate `merge_group` trigger. Otherwise, those required checks do not run when a pull request enters the queue, and the merge cannot complete.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request:
+    branches:
+      - main
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+    branches:
+      - main
+  merge_group:
+    types:
+      - checks_requested
+```
+
+
+## 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
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [
+  {
+    files: ["**/*.{yml,yaml}"],
+    plugins: {
+      "github-actions": githubActions,
+    },
+    rules: {
+      "github-actions/require-merge-group-trigger": "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.
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onmerge_grouptypes](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onmerge_grouptypes)