eslint-plugin-github-actions-2 1.0.0

package/docs/rules/require-workflow-concurrency.md

@@ -0,0 +1,73 @@
+# require-workflow-concurrency
+
+> **Rule catalog ID:** R004
+
+## Targeted pattern scope
+
+Workflows that listen for `push`, `pull_request`, `pull_request_target`, `workflow_dispatch`, or `merge_group` by default.
+
+## What this rule reports
+
+This rule reports workflows that should define top-level `concurrency` but do not, as well as concurrency blocks that omit `group` or `cancel-in-progress`.
+
+## Why this rule exists
+
+Concurrency helps cancel superseded runs so repeated pushes and pull request updates do not create long backlogs of redundant workflow executions.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+```
+
+```yaml
+concurrency:
+  group: ci
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: 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/require-workflow-concurrency": "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#concurrency](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#concurrency)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)

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

@@ -0,0 +1,70 @@
+# require-workflow-dispatch-input-type
+
+> **Rule catalog ID:** R022
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define `on.workflow_dispatch.inputs`.
+
+## What this rule reports
+
+This rule reports manual-dispatch inputs that omit `type` or set `type` to an empty or non-string value.
+
+## Why this rule exists
+
+Explicit input types make manual workflows easier to use in the GitHub UI, preserve boolean and number semantics more reliably, and keep workflow interfaces self-documenting as they evolve.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Deployment target
+        required: true
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Deployment target
+        required: true
+        type: environment
+```
+
+
+## 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-dispatch-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/reference/workflows-and-actions/workflow-syntax#onworkflow_dispatchinputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_dispatchinputs)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_dispatchinputsinput_idtype](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_dispatchinputsinput_idtype)
+- [https://docs.github.com/actions/reference/workflows-and-actions/contexts#inputs-context](https://docs.github.com/actions/reference/workflows-and-actions/contexts#inputs-context)

package/docs/rules/require-workflow-interface-description.md

@@ -0,0 +1,96 @@
+# require-workflow-interface-description
+
+> **Rule catalog ID:** R024
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that expose manual or reusable workflow interfaces.
+
+## What this rule reports
+
+This rule reports missing or empty `description` fields for:
+
+- `on.workflow_dispatch.inputs.*`
+- `on.workflow_call.inputs.*`
+- `on.workflow_call.secrets.*`
+- `on.workflow_call.outputs.*`
+
+## Why this rule exists
+
+Manual workflow forms and reusable workflows behave like public interfaces for your automation. Requiring descriptions keeps those interfaces self-documenting for operators, reviewers, and downstream workflow authors.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        required: true
+        type: environment
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Deployment target environment
+        required: true
+        type: environment
+```
+
+## Additional examples
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      config-path:
+        description: Path to the deployment config
+        required: true
+        type: string
+    secrets:
+      token:
+        description: Token used to publish deployment state
+        required: true
+    outputs:
+      deployment-url:
+        description: Final deployment URL
+        value: ${{ jobs.deploy.outputs.url }}
+```
+
+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-interface-description": "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#onworkflow_dispatchinputs](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_dispatchinputs)
+- [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_callsecrets](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callsecrets)
+- [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/require-workflow-permissions.md

@@ -0,0 +1,75 @@
+# require-workflow-permissions
+
+> **Rule catalog ID:** R001
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define one or more jobs.
+
+## What this rule reports
+
+This rule reports workflows that omit explicit token `permissions` entirely, or jobs that omit `permissions` when the workflow does not define them globally.
+
+## Why this rule exists
+
+GitHub recommends using least-privilege `GITHUB_TOKEN` permissions instead of relying on broader defaults. Declaring `permissions` explicitly makes token scope reviewable and repeatable.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+```
+
+```yaml
+jobs:
+  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/require-workflow-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)

package/docs/rules/require-workflow-run-branches.md

@@ -0,0 +1,66 @@
+# require-workflow-run-branches
+
+> **Rule catalog ID:** R028
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that use the `workflow_run` trigger.
+
+## What this rule reports
+
+This rule reports `on.workflow_run` triggers that do not declare a non-empty `branches` or `branches-ignore` filter.
+
+## Why this rule exists
+
+`workflow_run` is often used for follow-up workflows that have more privileges than the upstream workflow that triggered them. Requiring branch scoping keeps these follow-up workflows from reacting to every upstream branch indiscriminately and matches GitHub's documented trigger-filtering capabilities.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    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/require-workflow-run-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/workflow-syntax#onworkflow_runbranchesbranches-ignore](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_runbranchesbranches-ignore)
+- [https://wellarchitected.github.com/library/application-security/recommendations/actions-security/](https://wellarchitected.github.com/library/application-security/recommendations/actions-security/)

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

@@ -0,0 +1,58 @@
+# require-workflow-template-pair
+
+> **Rule catalog ID:** R054
+
+## Targeted pattern scope
+
+Workflow template YAML files under `workflow-templates/`.
+
+## What this rule reports
+
+Reports template YAML files without matching `.properties.json` metadata files.
+
+## Why this rule exists
+
+Template metadata is required for correct template presentation in the workflow chooser.
+
+## ❌ Incorrect
+
+```text
+workflow-templates/ci.yml
+```
+
+## ✅ Correct
+
+```text
+workflow-templates/ci.yml
+workflow-templates/ci.properties.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-workflow-template-pair": "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-workflow-template-properties-pair.md

@@ -0,0 +1,58 @@
+# require-workflow-template-properties-pair
+
+> **Rule catalog ID:** R055
+
+## Targeted pattern scope
+
+Workflow-template metadata files ending with `.properties.json`.
+
+## What this rule reports
+
+Reports metadata files that do not have matching `.yml`/`.yaml` template workflow files.
+
+## Why this rule exists
+
+Orphan metadata files are dead configuration and mislead maintainers.
+
+## ❌ Incorrect
+
+```text
+workflow-templates/ci.properties.json
+```
+
+## ✅ Correct
+
+```text
+workflow-templates/ci.properties.json
+workflow-templates/ci.yml
+```
+
+
+## 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-template-properties-pair": "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/valid-timeout-minutes.md

@@ -0,0 +1,74 @@
+# valid-timeout-minutes
+
+> **Rule catalog ID:** R017
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that set `timeout-minutes` on jobs or steps.
+
+## What this rule reports
+
+This rule reports literal `timeout-minutes` values that are not positive integers or that fall outside the configured allowed range.
+
+## Why this rule exists
+
+Timeout values are operational safety limits. Invalid or out-of-policy values can lead to stuck runners, wasted compute, or unexpectedly long execution windows.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 0
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+```
+
+```yaml
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: ${{ fromJSON(vars.JOB_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/valid-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)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepscontinue-on-error](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepscontinue-on-error)

package/docs/rules/valid-trigger-events.md

@@ -0,0 +1,62 @@
+# valid-trigger-events
+
+> **Rule catalog ID:** R018
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that declare trigger events under `on`.
+
+## What this rule reports
+
+This rule reports trigger event names that are not documented GitHub Actions workflow events.
+
+## Why this rule exists
+
+Mistyped trigger names silently break workflow intent. Validating events early prevents workflows from never running, or from running at the wrong time.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  foo_bar:
+```
+
+## ✅ 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/valid-trigger-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](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows)
+- [https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#on](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#on)