eslint-plugin-github-actions-2 1.0.0

package/docs/rules/no-post-if-without-post.md

@@ -0,0 +1,64 @@
+# no-post-if-without-post
+
+> **Rule catalog ID:** R046
+
+## Targeted pattern scope
+
+Action metadata `runs.post-if` declarations.
+
+## What this rule reports
+
+Reports `runs.post-if` when `runs.post` is missing.
+
+## Why this rule exists
+
+`post-if` has no effect without a matching `post` hook.
+
+## ❌ Incorrect
+
+```yaml
+runs:
+  using: node20
+  main: dist/index.js
+  post-if: runner.os == 'Linux'
+```
+
+## ✅ Correct
+
+```yaml
+runs:
+  using: node20
+  main: dist/index.js
+  post: dist/cleanup.js
+  post-if: runner.os == 'Linux'
+```
+
+
+## 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-post-if-without-post": "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-javascript-actions](https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#runs-for-javascript-actions)

package/docs/rules/no-pr-head-checkout-in-pull-request-target.md

@@ -0,0 +1,83 @@
+# no-pr-head-checkout-in-pull-request-target
+
+> **Rule catalog ID:** R030
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files triggered by `pull_request_target` that use `actions/checkout`.
+
+## What this rule reports
+
+This rule reports `actions/checkout` steps in `pull_request_target` workflows when `with.ref` or `with.repository` points at the pull request head branch, SHA, or repository.
+
+## Why this rule exists
+
+GitHub warns that `pull_request_target` runs with the base repository's privileges and should not be used to build or run untrusted code from the pull request. Checking out the PR head inside this privileged trigger is a common way to accidentally create a "pwn request" workflow.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request_target:
+
+jobs:
+  annotate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request_target:
+
+jobs:
+  annotate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v8
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: "Thanks for the PR!"
+            });
+```
+
+
+## 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-pr-head-checkout-in-pull-request-target": "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/no-pre-if-without-pre.md

@@ -0,0 +1,64 @@
+# no-pre-if-without-pre
+
+> **Rule catalog ID:** R045
+
+## Targeted pattern scope
+
+Action metadata `runs.pre-if` declarations.
+
+## What this rule reports
+
+Reports `runs.pre-if` when `runs.pre` is missing.
+
+## Why this rule exists
+
+`pre-if` has no effect unless a `pre` hook exists.
+
+## ❌ Incorrect
+
+```yaml
+runs:
+  using: node20
+  main: dist/index.js
+  pre-if: runner.os == 'Linux'
+```
+
+## ✅ Correct
+
+```yaml
+runs:
+  using: node20
+  pre: dist/setup.js
+  pre-if: runner.os == 'Linux'
+  main: dist/index.js
+```
+
+
+## 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-pre-if-without-pre": "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-javascript-actions](https://docs.github.com/actions/reference/workflows-and-actions/metadata-syntax#runs-for-javascript-actions)

package/docs/rules/no-required-input-with-default.md

@@ -0,0 +1,64 @@
+# no-required-input-with-default
+
+> **Rule catalog ID:** R047
+
+## Targeted pattern scope
+
+Action metadata `inputs.<id>` definitions.
+
+## What this rule reports
+
+Reports input definitions that set both `required: true` and `default`.
+
+## Why this rule exists
+
+A default value means callers can omit the input, which conflicts with `required: true`.
+
+## ❌ Incorrect
+
+```yaml
+inputs:
+  token:
+    description: Token
+    required: true
+    default: abc123
+```
+
+## ✅ Correct
+
+```yaml
+inputs:
+  token:
+    description: Token
+    required: true
+```
+
+
+## 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-required-input-with-default": "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-secrets-in-if.md

@@ -0,0 +1,70 @@
+# no-secrets-in-if
+
+> **Rule catalog ID:** R027
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files with job-level or step-level `if` conditionals.
+
+## What this rule reports
+
+This rule reports `if` conditionals that directly reference the `secrets` context, such as `secrets.DEPLOY_TOKEN`.
+
+## Why this rule exists
+
+GitHub documents that secrets cannot be directly referenced in `if:` conditionals. The safe pattern is to assign the secret to an environment variable first, then check the environment variable inside the conditional.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - if: ${{ secrets.DEPLOY_TOKEN != '' }}
+        run: ./deploy.sh
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+    steps:
+      - if: ${{ env.DEPLOY_TOKEN != '' }}
+        run: ./deploy.sh
+```
+
+
+## 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-secrets-in-if": "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_idstepsif](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsif)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif)

package/docs/rules/no-self-hosted-runner-on-fork-pr-events.md

@@ -0,0 +1,75 @@
+# no-self-hosted-runner-on-fork-pr-events
+
+> **Rule catalog ID:** R036
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files triggered by fork-capable pull request events such as `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment`, and `issue_comment`.
+
+## What this rule reports
+
+This rule reports jobs that select a self-hosted runner while the workflow can be invoked from forked or Dependabot pull request activity.
+
+## Why this rule exists
+
+GitHub documents that forked pull request activity is sent to the base repository for these PR-related events, and that self-hosted runners do not provide the same clean, ephemeral isolation guarantees as GitHub-hosted runners. Running untrusted contributor-triggered workflows on self-hosted infrastructure can expose secrets, tokens, network access, or persistent runner state.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on:
+      - self-hosted
+      - linux
+    steps:
+      - run: npm test
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - 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/no-self-hosted-runner-on-fork-pr-events": "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](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request)
+- [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#hardening-for-self-hosted-runners](https://docs.github.com/actions/reference/security/secure-use#hardening-for-self-hosted-runners)

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

@@ -0,0 +1,57 @@
+# no-subdirectory-template-file-pattern
+
+> **Rule catalog ID:** R062
+
+## Targeted pattern scope
+
+`filePatterns` entries in workflow-template properties metadata.
+
+## What this rule reports
+
+Reports patterns containing path separators that target subdirectories.
+
+## Why this rule exists
+
+Workflow-template `filePatterns` are intended to match repository-root indicators.
+
+## ❌ Incorrect
+
+```json
+{ "filePatterns": ["^src/package.json$"] }
+```
+
+## ✅ Correct
+
+```json
+{ "filePatterns": ["^package.json$", "^go\\.mod$"] }
+```
+
+
+## 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-subdirectory-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-template-placeholder-in-non-template-workflow.md

@@ -0,0 +1,63 @@
+# no-template-placeholder-in-non-template-workflow
+
+> **Rule catalog ID:** R069
+
+## Targeted pattern scope
+
+Regular workflow YAML files outside `workflow-templates/`.
+
+## What this rule reports
+
+Reports usage of `$default-branch` placeholder tokens.
+
+## Why this rule exists
+
+`$default-branch` is a template-only token and should not appear in normal workflow files.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+    branches:
+      - $default-branch
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+```
+
+
+## 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-template-placeholder-in-non-template-workflow": "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/no-top-level-env.md

@@ -0,0 +1,64 @@
+# no-top-level-env
+
+> **Rule catalog ID:** R013
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare `env` at the top level.
+
+## What this rule reports
+
+This rule reports workflows that define a top-level `env` block.
+
+## Why this rule exists
+
+Top-level environment variables affect every job and can hide which parts of a workflow actually depend on a variable. Narrower scoping keeps workflow behavior easier to audit.
+
+## ❌ Incorrect
+
+```yaml
+env:
+  NODE_ENV: production
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: production
+```
+
+
+## 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-top-level-env": "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#env](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#env)
+- [https://docs.github.com/actions/learn-github-actions/variables](https://docs.github.com/actions/learn-github-actions/variables)

package/docs/rules/no-top-level-permissions.md

@@ -0,0 +1,64 @@
+# no-top-level-permissions
+
+> **Rule catalog ID:** R014
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare `permissions` at the top level.
+
+## What this rule reports
+
+This rule reports workflows that define top-level `permissions` instead of scoping token permissions per job.
+
+## Why this rule exists
+
+Some teams want every job to declare the exact token scope it needs so that permission review happens at the job boundary rather than once per workflow.
+
+## ❌ Incorrect
+
+```yaml
+permissions:
+  contents: read
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    name: Build
+    permissions:
+      contents: read
+    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/no-top-level-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-for-github-actions/security-guides/automatic-token-authentication](https://docs.github.com/actions/security-for-github-actions/security-guides/automatic-token-authentication)