eslint-plugin-github-actions-2 1.0.0

package/docs/rules/require-pull-request-target-branches.md

@@ -0,0 +1,79 @@
+# require-pull-request-target-branches
+
+> **Rule catalog ID:** R032
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files triggered by `pull_request_target`.
+
+## What this rule reports
+
+This rule reports `pull_request_target` triggers that do not scope the target base branches with `branches` or `branches-ignore`.
+
+## Why this rule exists
+
+`pull_request_target` runs in the base repository context and can access privileges that ordinary forked pull request workflows do not. Adding branch filters narrows where that privileged automation can run and reduces accidental exposure across every protected branch.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request_target:
+    types:
+      - opened
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo privileged automation
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request_target:
+    types:
+      - opened
+    branches:
+      - main
+      - releases/**
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo privileged automation
+```
+
+
+## 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-pull-request-target-branches": "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#pull_request_target](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target)
+- [https://docs.github.com/actions/reference/security/secure-use](https://docs.github.com/actions/reference/security/secure-use)

package/docs/rules/require-run-step-shell.md

@@ -0,0 +1,85 @@
+# 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
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install
+        run: npm ci
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install
+        shell: bash
+        run: npm ci
+```
+
+## Additional examples
+
+```yaml
+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
+
+```ts
+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.
+
+## Further reading
+
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#defaultsrunshell](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#defaultsrunshell)
+- [https://github.com/rhysd/actionlint/issues/374](https://github.com/rhysd/actionlint/issues/374)

package/docs/rules/require-template-categories.md

@@ -0,0 +1,62 @@
+# require-template-categories
+
+> **Rule catalog ID:** R057
+
+## Targeted pattern scope
+
+Workflow-template metadata `categories` property.
+
+## What this rule reports
+
+Reports missing or empty `categories` arrays.
+
+## Why this rule exists
+
+Categories improve filterability and ranking in the workflow template chooser.
+
+## ❌ Incorrect
+
+```json
+{ "name": "CI", "description": "Template", "iconName": "workflow" }
+```
+
+## ✅ Correct
+
+```json
+{
+  "name": "CI",
+  "description": "Template",
+  "iconName": "workflow",
+  "categories": ["JavaScript"]
+}
+```
+
+
+## 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-template-categories": "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/reusing-workflow-configurations#metadata-file-requirements](https://docs.github.com/actions/reference/workflows-and-actions/reusing-workflow-configurations#metadata-file-requirements)

package/docs/rules/require-template-file-patterns.md

@@ -0,0 +1,63 @@
+# require-template-file-patterns
+
+> **Rule catalog ID:** R058
+
+## Targeted pattern scope
+
+Workflow-template metadata `filePatterns` property.
+
+## What this rule reports
+
+Reports missing or empty `filePatterns` arrays.
+
+## Why this rule exists
+
+File patterns help GitHub suggest relevant templates for repository contents.
+
+## ❌ Incorrect
+
+```json
+{ "name": "CI", "description": "Template", "iconName": "workflow" }
+```
+
+## ✅ Correct
+
+```json
+{
+  "name": "CI",
+  "description": "Template",
+  "iconName": "workflow",
+  "categories": ["JavaScript"],
+  "filePatterns": ["package.json$"]
+}
+```
+
+
+## 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-template-file-patterns": "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/reusing-workflow-configurations#metadata-file-requirements](https://docs.github.com/actions/reference/workflows-and-actions/reusing-workflow-configurations#metadata-file-requirements)

package/docs/rules/require-template-icon-file-exists.md

@@ -0,0 +1,61 @@
+# require-template-icon-file-exists
+
+> **Rule catalog ID:** R065
+
+## Targeted pattern scope
+
+Workflow-template properties `iconName` values that refer to local SVG icons.
+
+## What this rule reports
+
+Reports local `iconName` values that do not resolve to an existing `*.svg` file.
+
+## Why this rule exists
+
+Broken icon references degrade workflow-template UX.
+
+## ❌ Incorrect
+
+```json
+{ "iconName": "workflow" }
+```
+
+If `workflow.svg` does not exist next to the metadata file, this is reported.
+
+## ✅ Correct
+
+```json
+{ "iconName": "workflow" }
+```
+
+With `workflow.svg` present in the same directory.
+
+
+## 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-template-icon-file-exists": "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/reusing-workflow-configurations#metadata-file-requirements](https://docs.github.com/actions/reference/workflows-and-actions/reusing-workflow-configurations#metadata-file-requirements)

package/docs/rules/require-template-icon-name.md

@@ -0,0 +1,57 @@
+# require-template-icon-name
+
+> **Rule catalog ID:** R056
+
+## Targeted pattern scope
+
+Workflow-template metadata `iconName` property.
+
+## What this rule reports
+
+Reports metadata files missing `iconName` or setting it to an empty value.
+
+## Why this rule exists
+
+An icon improves template discoverability and chooser UX.
+
+## ❌ Incorrect
+
+```json
+{ "name": "CI", "description": "Template" }
+```
+
+## ✅ Correct
+
+```json
+{ "name": "CI", "description": "Template", "iconName": "workflow" }
+```
+
+
+## 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-template-icon-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/reusing-workflow-configurations#metadata-file-requirements](https://docs.github.com/actions/reference/workflows-and-actions/reusing-workflow-configurations#metadata-file-requirements)

package/docs/rules/require-template-workflow-name.md

@@ -0,0 +1,60 @@
+# require-template-workflow-name
+
+> **Rule catalog ID:** R067
+
+## Targeted pattern scope
+
+Workflow template YAML files under `workflow-templates/`.
+
+## What this rule reports
+
+Reports missing or empty top-level `name` fields.
+
+## Why this rule exists
+
+Template names are primary labels shown in workflow selection UI.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+```
+
+## ✅ Correct
+
+```yaml
+name: Node.js 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-template-workflow-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/reusing-workflow-configurations](https://docs.github.com/actions/reference/workflows-and-actions/reusing-workflow-configurations)

package/docs/rules/require-trigger-types.md

@@ -0,0 +1,76 @@
+# require-trigger-types
+
+> **Rule catalog ID:** R031
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that use configurable multi-activity events without an explicit `types` filter.
+
+## What this rule reports
+
+This rule reports selected workflow events such as `issue_comment`, `pull_request_review`, `repository_dispatch`, `workflow_run`, `merge_group`, and similar multi-activity triggers when they omit `types`.
+
+## Why this rule exists
+
+GitHub documents that these events support multiple activity types and default to reacting to all supported activities when `types` is omitted. Requiring `types` keeps automation specific, easier to review, and less likely to run on unintended actions.
+
+This rule intentionally targets event families where explicit activity scoping is especially useful, rather than requiring `types` for every possible trigger.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  issue_comment:
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo comment received
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  issue_comment:
+    types:
+      - created
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo comment received
+```
+
+
+## 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-trigger-types": "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](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onevent_nametypes)

package/docs/rules/require-workflow-call-input-type.md

@@ -0,0 +1,70 @@
+# require-workflow-call-input-type
+
+> **Rule catalog ID:** R034
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define `on.workflow_call.inputs` for reusable workflows.
+
+## What this rule reports
+
+This rule reports reusable workflow inputs that omit `type` or set `type` to a value outside GitHub's documented `string`, `number`, and `boolean` reusable-workflow input types.
+
+## Why this rule exists
+
+Reusable workflows are interfaces consumed by other workflows. Explicitly typed inputs make those interfaces clearer for callers, help GitHub validate passed values consistently, and reduce ambiguity when workflows evolve.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      dry_run:
+        description: Run validation only
+        required: false
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      dry_run:
+        description: Run validation only
+        required: false
+        type: boolean
+```
+
+
+## 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-workflow-call-input-type": "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/using-workflows/reusing-workflows](https://docs.github.com/actions/using-workflows/reusing-workflows)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callinputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callinputs)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callinputsinput_idtype](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callinputsinput_idtype)

package/docs/rules/require-workflow-call-output-value.md

@@ -0,0 +1,67 @@
+# require-workflow-call-output-value
+
+> **Rule catalog ID:** R039
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define reusable workflow outputs under `on.workflow_call.outputs`.
+
+## What this rule reports
+
+This rule reports reusable workflow outputs that omit `value` or set it to an empty scalar.
+
+## Why this rule exists
+
+Reusable workflow outputs are part of the public interface exposed to callers. GitHub documents each `workflow_call` output as having a `value`, and without that mapping the output cannot return anything meaningful to downstream jobs.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_call:
+    outputs:
+      deployment-url:
+        description: Published deployment URL
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_call:
+    outputs:
+      deployment-url:
+        description: Published deployment URL
+        value: ${{ jobs.deploy.outputs.url }}
+```
+
+
+## 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-workflow-call-output-value": "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/using-workflows/reusing-workflows](https://docs.github.com/actions/using-workflows/reusing-workflows)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_calloutputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_calloutputs)