eslint-plugin-github-actions-2 1.0.2 → 1.0.4

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

@@ -1,22 +1,33 @@
-# `githubActions.configs.workflowTemplates`
-
-Workflow template package linting for both template YAML and metadata files.
-
+---
+sidebar_position: 5
+---
+
+# `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)
+Fix legend:
+
+- 🔧 = autofixable
+- 💡 = suggestions available
+- — = report only
 
+| Rule | Fix |
+| --- | :-: |
+| <span class="sb-inline-rule-number">R060</span> [`no-empty-template-file-pattern`](../no-empty-template-file-pattern.md) | 🔧 |
+| <span class="sb-inline-rule-number">R068</span> [`no-hardcoded-default-branch-in-template`](../no-hardcoded-default-branch-in-template.md) | — |
+| <span class="sb-inline-rule-number">R063</span> [`no-icon-file-extension-in-template-icon-name`](../no-icon-file-extension-in-template-icon-name.md) | 🔧 |
+| <span class="sb-inline-rule-number">R059</span> [`no-invalid-template-file-pattern-regex`](../no-invalid-template-file-pattern-regex.md) | — |
+| <span class="sb-inline-rule-number">R064</span> [`no-path-separators-in-template-icon-name`](../no-path-separators-in-template-icon-name.md) | 💡 |
+| <span class="sb-inline-rule-number">R062</span> [`no-subdirectory-template-file-pattern`](../no-subdirectory-template-file-pattern.md) | — |
+| <span class="sb-inline-rule-number">R061</span> [`no-universal-template-file-pattern`](../no-universal-template-file-pattern.md) | — |
+| <span class="sb-inline-rule-number">R066</span> [`prefer-template-yml-extension`](../prefer-template-yml-extension.md) | — |
+| <span class="sb-inline-rule-number">R057</span> [`require-template-categories`](../require-template-categories.md) | — |
+| <span class="sb-inline-rule-number">R058</span> [`require-template-file-patterns`](../require-template-file-patterns.md) | — |
+| <span class="sb-inline-rule-number">R065</span> [`require-template-icon-file-exists`](../require-template-icon-file-exists.md) | — |
+| <span class="sb-inline-rule-number">R056</span> [`require-template-icon-name`](../require-template-icon-name.md) | — |
+| <span class="sb-inline-rule-number">R067</span> [`require-template-workflow-name`](../require-template-workflow-name.md) | — |
+| <span class="sb-inline-rule-number">R054</span> [`require-workflow-template-pair`](../require-workflow-template-pair.md) | — |
+| <span class="sb-inline-rule-number">R055</span> [`require-workflow-template-properties-pair`](../require-workflow-template-properties-pair.md) | — |

package/docs/rules/require-codeql-actions-read.md

@@ -0,0 +1,50 @@
+# require-codeql-actions-read
+
+> **Rule catalog ID:** R099
+
+## Targeted pattern scope
+
+Jobs that use CodeQL actions such as `init`, `analyze`, `autobuild`, or `upload-sarif`.
+
+## What this rule reports
+
+This rule reports CodeQL jobs that do not grant `actions: read`.
+
+## Why this rule exists
+
+CodeQL jobs commonly need `actions: read` for workflow metadata and action access. Requiring it explicitly keeps job permissions self-documenting and consistent.
+
+## ❌ Incorrect
+
+```yaml
+permissions:
+  contents: read
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  actions: read
+  contents: read
+```
+
+## Additional examples
+
+This rule is job-scoped: it only evaluates jobs that actually use CodeQL actions, not unrelated workflow jobs.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if your CodeQL setup demonstrably works without `actions: read` and you intentionally prefer the smaller permission set.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-codeql-branch-filters.md

@@ -0,0 +1,53 @@
+# require-codeql-branch-filters
+
+> **Rule catalog ID:** R113
+
+## Targeted pattern scope
+
+CodeQL workflows that define `push` or `pull_request` triggers as mappings.
+
+## What this rule reports
+
+This rule reports CodeQL `push` or `pull_request` triggers that do not define a non-empty `branches` or `branches-ignore` filter.
+
+## Why this rule exists
+
+Code scanning on every branch may be intentional, but for most repositories CodeQL is scoped to the main development branches. Requiring an explicit branch filter makes that intent visible and keeps trigger breadth reviewable.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push: {}
+  pull_request: {}
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+```
+
+## Additional examples
+
+This rule only checks CodeQL workflows and only when the trigger is expressed as a mapping where branch filters are supported.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if your repository intentionally wants CodeQL to react to every branch and that policy is already understood by maintainers.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-codeql-category-when-language-matrix.md

@@ -0,0 +1,49 @@
+# require-codeql-category-when-language-matrix
+
+> **Rule catalog ID:** R114
+
+## Targeted pattern scope
+
+CodeQL analyze steps inside jobs that use `strategy.matrix.language`.
+
+## What this rule reports
+
+This rule reports CodeQL analyze steps that do not set `with.category` to include `matrix.language` when the job uses a language matrix.
+
+## Why this rule exists
+
+When CodeQL runs in a language matrix, the SARIF category is the easiest way to keep uploads distinct and understandable in the code scanning UI. Requiring a matrix-aware category helps avoid ambiguous result grouping.
+
+## ❌ Incorrect
+
+```yaml
+- uses: github/codeql-action/analyze@v4
+```
+
+## ✅ Correct
+
+```yaml
+- uses: github/codeql-action/analyze@v4
+  with:
+    category: /language:${{ matrix.language }}
+```
+
+## Additional examples
+
+This rule only applies when the job uses a `language` matrix. Single-language CodeQL jobs are ignored.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if your repository intentionally accepts a shared category across matrix jobs and that grouping has already been reviewed.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-codeql-pull-request-trigger.md

@@ -0,0 +1,53 @@
+# require-codeql-pull-request-trigger
+
+> **Rule catalog ID:** R100
+
+## Targeted pattern scope
+
+Workflows that run CodeQL analysis.
+
+## What this rule reports
+
+This rule reports CodeQL workflows that do not listen for `pull_request`.
+
+## Why this rule exists
+
+Code scanning is most actionable when it runs against pull requests before merges happen. Requiring the PR trigger keeps CodeQL feedback in the developer loop.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+    branches: [main]
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+```
+
+## Additional examples
+
+This rule only checks workflows that actually use CodeQL actions; it will not report on unrelated scheduled security workflows.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if your repository intentionally runs CodeQL only outside pull requests, for example in an external CI system.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-codeql-schedule.md

@@ -0,0 +1,57 @@
+# require-codeql-schedule
+
+> **Rule catalog ID:** R101
+
+## Targeted pattern scope
+
+Workflows that run CodeQL analysis.
+
+## What this rule reports
+
+This rule reports CodeQL workflows that do not define a `schedule` trigger.
+
+## Why this rule exists
+
+Scheduled CodeQL runs catch newly added queries, engine improvements, and baseline issues that may not be re-evaluated often enough through push-only activity.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 0 * * 1"
+```
+
+## Additional examples
+
+This rule does not enforce a particular cron expression. It only requires that periodic re-analysis be configured.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if CodeQL scheduling is handled outside GitHub Actions or by organization-wide automation.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-codeql-security-events-write.md

@@ -0,0 +1,50 @@
+# require-codeql-security-events-write
+
+> **Rule catalog ID:** R098
+
+## Targeted pattern scope
+
+Jobs that run `github/codeql-action/analyze`.
+
+## What this rule reports
+
+This rule reports CodeQL analysis jobs that do not grant `security-events: write`.
+
+## Why this rule exists
+
+CodeQL analysis uploads results to GitHub code scanning. Without `security-events: write`, those results cannot be published correctly.
+
+## ❌ Incorrect
+
+```yaml
+permissions:
+  contents: read
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+```
+
+## Additional examples
+
+This rule complements `require-sarif-upload-security-events-write` by covering CodeQL analysis jobs directly, even when they do not use a separate SARIF upload step.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule only if CodeQL results are uploaded through a different mechanism outside the workflow.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-dependabot-assignees.md

@@ -0,0 +1,64 @@
+# require-dependabot-assignees
+
+> **Rule catalog ID:** R077
+
+## Targeted pattern scope
+
+Dependabot update entries and multi-ecosystem groups that control pull request ownership.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to a non-empty `assignees` list, either directly or via `multi-ecosystem-groups` inheritance.
+
+## Why this rule exists
+
+Dependabot pull requests are easy to ignore when they are unowned. Requiring assignees makes update responsibility explicit and improves triage speed.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+    assignees:
+      - "octocat"
+```
+
+## Additional examples
+
+This rule also accepts assignees inherited from a `multi-ecosystem-group`, which is often the cleanest way to keep ownership consistent across multiple update entries.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule when ownership is handled exclusively through CODEOWNERS, bots, or external automation and explicit assignees would be noisy.
+
+## Further reading
+
+- [Dependabot options reference: assignees](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#assignees--)
+- [Customizing Dependabot pull requests: Automatically adding assignees](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#automatically-adding-assignees)

package/docs/rules/require-dependabot-automation-permissions.md

@@ -0,0 +1,53 @@
+# require-dependabot-automation-permissions
+
+> **Rule catalog ID:** R111
+
+## Targeted pattern scope
+
+Jobs that automate Dependabot pull requests using `gh pr edit`, `gh pr review`, or `gh pr merge`.
+
+## What this rule reports
+
+This rule reports missing minimum permissions for Dependabot pull request automation steps.
+
+## Why this rule exists
+
+PR automation should request only the permissions it actually needs, but it still needs enough privilege to work. This rule makes those minimum permission requirements explicit for common `gh pr` automation commands.
+
+## ❌ Incorrect
+
+```yaml
+permissions:
+  contents: read
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+```
+
+## Additional examples
+
+- `gh pr edit --add-label` requires `issues: write`
+- `gh pr review` requires `pull-requests: write`
+- `gh pr merge` requires `contents: write` and `pull-requests: write`
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if your repository uses a different automation mechanism instead of `gh pr` commands.
+
+## Further reading
+
+- [Automating Dependabot with GitHub Actions](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/automating-dependabot-with-github-actions)

package/docs/rules/require-dependabot-automation-pull-request-trigger.md

@@ -0,0 +1,49 @@
+# require-dependabot-automation-pull-request-trigger
+
+> **Rule catalog ID:** R112
+
+## Targeted pattern scope
+
+Workflows that automate Dependabot pull requests.
+
+## What this rule reports
+
+This rule reports Dependabot automation workflows that do not listen for `pull_request`.
+
+## Why this rule exists
+
+Dependabot pull request automation should run where Dependabot actually creates pull requests. Requiring the `pull_request` trigger keeps the workflow attached to the right event surface.
+
+## ❌ Incorrect
+
+```yaml
+on: [workflow_dispatch]
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+    branches: [main]
+```
+
+## Additional examples
+
+This rule applies only when the workflow contains known Dependabot automation patterns such as `dependabot/fetch-metadata` or `gh pr` automation commands.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if your repository automates Dependabot outside `pull_request` workflows on purpose.
+
+## Further reading
+
+- [Automating Dependabot with GitHub Actions](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/automating-dependabot-with-github-actions)

package/docs/rules/require-dependabot-bot-actor-guard.md

@@ -0,0 +1,52 @@
+# require-dependabot-bot-actor-guard
+
+> **Rule catalog ID:** R109
+
+## Targeted pattern scope
+
+Jobs that automate Dependabot pull requests using `dependabot/fetch-metadata` or `gh pr` commands.
+
+## What this rule reports
+
+This rule reports Dependabot automation jobs that do not guard execution on `dependabot[bot]`.
+
+## Why this rule exists
+
+Pull request automation should not run broadly on all pull requests when it is intended specifically for Dependabot. Requiring a Dependabot bot guard makes that safety boundary explicit.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  dependabot:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+```
+
+## Additional examples
+
+This rule accepts either a job-level guard or step-level guards on the relevant automation steps.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if your automation intentionally handles both Dependabot and non-Dependabot pull requests in the same job.
+
+## Further reading
+
+- [Automating Dependabot with GitHub Actions](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/automating-dependabot-with-github-actions)

package/docs/rules/require-dependabot-commit-message-include-scope.md

@@ -0,0 +1,58 @@
+# require-dependabot-commit-message-include-scope
+
+> **Rule catalog ID:** R089
+
+## Targeted pattern scope
+
+Dependabot `commit-message` configuration, including values inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to `commit-message.include: "scope"`.
+
+## Why this rule exists
+
+Including scope in Dependabot commit messages makes pull request titles more informative by distinguishing production and development dependency updates. That extra context is useful for triage and automation.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    commit-message:
+      prefix: "deps"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+```
+
+## Additional examples
+
+This rule is especially helpful when grouped updates would otherwise produce similar-looking pull request titles across dependency classes.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally prefers shorter Dependabot titles without dependency scope markers.
+
+## Further reading
+
+- [Dependabot options reference: commit-message](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#commit-message--)