eslint-plugin-github-actions-2 1.0.0

package/docs/rules/no-universal-template-file-pattern.md

@@ -0,0 +1,57 @@
+# no-universal-template-file-pattern
+
+> **Rule catalog ID:** R061
+
+## Targeted pattern scope
+
+`filePatterns` entries in workflow-template properties metadata.
+
+## What this rule reports
+
+Reports universal catch-all patterns such as `.*`, `^.*$`, `.+`, and `^.+$`.
+
+## Why this rule exists
+
+Catch-all patterns degrade template recommendation precision.
+
+## ❌ Incorrect
+
+```json
+{ "filePatterns": [".*"] }
+```
+
+## ✅ Correct
+
+```json
+{ "filePatterns": ["package.json$", "^Cargo\\.toml$"] }
+```
+
+
+## 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/no-universal-template-file-pattern": "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/no-unknown-input-reference-in-composite.md

@@ -0,0 +1,71 @@
+# no-unknown-input-reference-in-composite
+
+> **Rule catalog ID:** R050
+
+## Targeted pattern scope
+
+Composite action metadata strings that reference `inputs.<id>`.
+
+## What this rule reports
+
+Reports `inputs.<id>` references when `<id>` is not declared under `inputs`.
+
+## Why this rule exists
+
+Typos in input references make composite actions behave incorrectly at runtime.
+
+## ❌ Incorrect
+
+```yaml
+inputs:
+  token:
+    description: Token
+runs:
+  using: composite
+  steps:
+    - run: echo "${{ inputs.tokne }}"
+      shell: bash
+```
+
+## ✅ Correct
+
+```yaml
+inputs:
+  token:
+    description: Token
+runs:
+  using: composite
+  steps:
+    - run: echo "${{ inputs.token }}"
+      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/no-unknown-input-reference-in-composite": "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#inputs](https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#inputs)

package/docs/rules/no-unknown-job-output-reference.md

@@ -0,0 +1,88 @@
+# no-unknown-job-output-reference
+
+> **Rule catalog ID:** R037
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that reference job outputs through `needs.<job_id>.outputs.<output_name>` or reusable workflow outputs through `jobs.<job_id>.outputs.<output_name>`.
+
+## What this rule reports
+
+This rule reports output references that point at:
+
+- a job that does not exist
+- a job that is not listed in the current job's direct `needs`
+- an output name that is not declared under the referenced job's `outputs`
+
+## Why this rule exists
+
+GitHub only populates the `needs` context for direct dependencies, and reusable workflow outputs must be mapped from declared job outputs. Typos in job IDs, missing `needs` dependencies, or misspelled output names silently evaluate to empty strings at runtime and can break downstream deployment, release, or reporting logic.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      artifact-sha: ${{ steps.pkg.outputs.sha }}
+    steps:
+      - id: pkg
+        run: echo "sha=abc123" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "${{ needs.build.outputs.artifact_sha }}"
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      artifact-sha: ${{ steps.pkg.outputs.sha }}
+    steps:
+      - id: pkg
+        run: echo "sha=abc123" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "${{ needs.build.outputs.artifact-sha }}"
+```
+
+
+## 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/no-unknown-job-output-reference": "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/contexts#needs-context](https://docs.github.com/actions/reference/workflows-and-actions/contexts#needs-context)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs)
+- [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)

package/docs/rules/no-unknown-step-reference.md

@@ -0,0 +1,73 @@
+# no-unknown-step-reference
+
+> **Rule catalog ID:** R038
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that reference the `steps` context.
+
+## What this rule reports
+
+This rule reports `steps.<id>.*` references when the referenced step ID does not exist in the job, or when a step tries to read the `steps` context from a later step that has not run yet.
+
+## Why this rule exists
+
+GitHub documents that the `steps` context only contains steps in the current job that have an `id` and have already run. A typo in `steps.<id>` or a forward reference to a later step resolves to missing data at runtime and can invalidate job outputs, environment URLs, or step conditionals.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Use result too early
+        run: echo "${{ steps.publish.outputs.url }}"
+      - id: publish
+        run: echo "url=https://example.com" >> "$GITHUB_OUTPUT"
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: publish
+        run: echo "url=https://example.com" >> "$GITHUB_OUTPUT"
+      - name: Use published URL
+        run: echo "${{ steps.publish.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/no-unknown-step-reference": "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/contexts#steps-context](https://docs.github.com/actions/reference/workflows-and-actions/contexts#steps-context)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsid](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsid)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs)

package/docs/rules/no-untrusted-input-in-run.md

@@ -0,0 +1,74 @@
+# no-untrusted-input-in-run
+
+> **Rule catalog ID:** R029
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files with inline `run` scripts that interpolate event payload values directly.
+
+## What this rule reports
+
+This rule reports `run` steps that directly embed untrusted event payload values such as pull request titles, issue bodies, comment bodies, review bodies, discussion text, or `repository_dispatch` client payload fields.
+
+## Why this rule exists
+
+GitHub recommends using an intermediate environment variable instead of interpolating untrusted context values directly into generated shell scripts. That reduces script-injection risk and makes the data flow easier to review.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "${{ github.event.pull_request.title }}"
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: echo "$PR_TITLE"
+```
+
+
+## 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/no-untrusted-input-in-run": "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/security/secure-use#good-practices-for-mitigating-script-injection-attacks](https://docs.github.com/actions/reference/security/secure-use#good-practices-for-mitigating-script-injection-attacks)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)

package/docs/rules/no-unused-input-in-composite.md

@@ -0,0 +1,71 @@
+# no-unused-input-in-composite
+
+> **Rule catalog ID:** R053
+
+## Targeted pattern scope
+
+Composite action inputs declared under `inputs`.
+
+## What this rule reports
+
+Reports declared inputs that are never referenced as `inputs.<id>`.
+
+## Why this rule exists
+
+Unused inputs increase maintenance burden and create confusing action interfaces.
+
+## ❌ Incorrect
+
+```yaml
+inputs:
+  token:
+    description: Token
+runs:
+  using: composite
+  steps:
+    - run: echo hello
+      shell: bash
+```
+
+## ✅ Correct
+
+```yaml
+inputs:
+  token:
+    description: Token
+runs:
+  using: composite
+  steps:
+    - run: echo "${{ inputs.token }}"
+      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/no-unused-input-in-composite": "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#inputs](https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#inputs)

package/docs/rules/no-write-all-permissions.md

@@ -0,0 +1,60 @@
+# no-write-all-permissions
+
+> **Rule catalog ID:** R023
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare `permissions`.
+
+## What this rule reports
+
+This rule reports workflow-level or job-level `permissions: write-all` declarations.
+
+## Why this rule exists
+
+GitHub recommends granting the `GITHUB_TOKEN` the least access needed. The `write-all` shortcut grants every writable scope at once, which makes reviews harder and increases the blast radius of a compromised workflow or third-party action.
+
+## ❌ Incorrect
+
+```yaml
+permissions: write-all
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+
+## 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/no-write-all-permissions": "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#permissions](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#permissions)
+- [https://docs.github.com/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token](https://docs.github.com/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token)

package/docs/rules/overview.md

@@ -0,0 +1,91 @@
+# Rule overview
+
+`eslint-plugin-github-actions-2` targets GitHub Actions workflow YAML files, action metadata files (`action.yml` / `action.yaml`), and workflow-template package files under `workflow-templates/`.
+
+New to the plugin? Start with [Getting started](./getting-started.md). Need
+config guidance? See the [preset reference](./presets/index.md). Looking for a
+specific check? Jump to [Current rules](#current-rules).
+
+## Included rule categories
+
+- **Security**: explicit least-privilege permissions and immutable SHA pinning
+- **Reliability**: bounded job timeouts
+- **Operations**: workflow concurrency controls and valid concurrency expression contexts
+- **Naming and readability**: workflow names, job IDs, job names, and step names
+- **Execution clarity**: explicit run-step shells, typed workflow interfaces, canonical manual-dispatch input access, and valid step-context references
+- **Workflow interface quality**: documented manual-dispatch and reusable workflow interfaces plus valid reusable output values and job-output mappings
+- **Reusable workflow hygiene**: explicit checkout ordering, narrowly scoped secret passing, and valid reusable-workflow caller job keys
+- **Workflow safety**: safer conditional secret handling, untrusted-script handling, scoped workflow chaining, safer privileged PR automation, fork-triggered self-hosted runner hardening, and scoped privileged PR targets
+- **Trigger precision**: explicit activity-type scoping for broad multi-activity events and merge-queue-aware pull request validation
+
+## Current 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-case-insensitive-input-id-collision`](./no-case-insensitive-input-id-collision.md)
+- [`no-composite-input-env-access`](./no-composite-input-env-access.md)
+- [`no-deprecated-node-runtime`](./no-deprecated-node-runtime.md)
+- [`no-duplicate-composite-step-id`](./no-duplicate-composite-step-id.md)
+- [`no-empty-template-file-pattern`](./no-empty-template-file-pattern.md)
+- [`no-external-job`](./no-external-job.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-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-template-file-pattern-regex`](./no-invalid-template-file-pattern-regex.md)
+- [`no-invalid-workflow-call-output-value`](./no-invalid-workflow-call-output-value.md)
+- [`no-path-separators-in-template-icon-name`](./no-path-separators-in-template-icon-name.md)
+- [`no-post-if-without-post`](./no-post-if-without-post.md)
+- [`no-pr-head-checkout-in-pull-request-target`](./no-pr-head-checkout-in-pull-request-target.md)
+- [`no-pre-if-without-pre`](./no-pre-if-without-pre.md)
+- [`no-required-input-with-default`](./no-required-input-with-default.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-subdirectory-template-file-pattern`](./no-subdirectory-template-file-pattern.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-top-level-permissions`](./no-top-level-permissions.md)
+- [`no-universal-template-file-pattern`](./no-universal-template-file-pattern.md)
+- [`no-unknown-input-reference-in-composite`](./no-unknown-input-reference-in-composite.md)
+- [`no-unknown-job-output-reference`](./no-unknown-job-output-reference.md)
+- [`no-unknown-step-reference`](./no-unknown-step-reference.md)
+- [`no-unused-input-in-composite`](./no-unused-input-in-composite.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-action-yml`](./prefer-action-yml.md)
+- [`prefer-file-extension`](./prefer-file-extension.md)
+- [`prefer-inputs-context`](./prefer-inputs-context.md)
+- [`prefer-step-uses-style`](./prefer-step-uses-style.md)
+- [`prefer-template-yml-extension`](./prefer-template-yml-extension.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-composite-step-name`](./require-composite-step-name.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-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-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)
+- [`require-workflow-template-pair`](./require-workflow-template-pair.md)
+- [`require-workflow-template-properties-pair`](./require-workflow-template-properties-pair.md)
+- [`valid-timeout-minutes`](./valid-timeout-minutes.md)
+- [`valid-trigger-events`](./valid-trigger-events.md)

package/docs/rules/pin-action-shas.md

@@ -0,0 +1,65 @@
+# pin-action-shas
+
+> **Rule catalog ID:** R003
+
+## Targeted pattern scope
+
+External step-level `uses:` actions and reusable workflow references.
+
+## What this rule reports
+
+This rule reports third-party `uses:` references that pin to mutable tags or branches instead of a full 40-character commit SHA.
+
+## Why this rule exists
+
+GitHub recommends pinning actions and reusable workflows to immutable SHAs because tags and branches can be retargeted after review.
+
+## ❌ Incorrect
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+```
+
+```yaml
+uses: owner/repo/.github/workflows/reuse.yml@main
+```
+
+## ✅ Correct
+
+```yaml
+steps:
+  - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
+```
+
+
+## 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/pin-action-shas": "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)
+- [https://docs.github.com/actions/using-workflows/reusing-workflows](https://docs.github.com/actions/using-workflows/reusing-workflows)
+- [https://docs.github.com/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions](https://docs.github.com/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions)