eslint-plugin-github-actions-2 1.0.0

package/docs/rules/no-hardcoded-default-branch-in-template.md

@@ -0,0 +1,63 @@
+# no-hardcoded-default-branch-in-template
+
+> **Rule catalog ID:** R068
+
+## Targeted pattern scope
+
+Workflow template YAML files under `workflow-templates/`.
+
+## What this rule reports
+
+Reports hardcoded `main` and `master` branch literals.
+
+## Why this rule exists
+
+Template workflows should use `$default-branch` so generated workflows match the target repository.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  push:
+    branches:
+      - $default-branch
+```
+
+
+## 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-hardcoded-default-branch-in-template": "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-icon-file-extension-in-template-icon-name.md

@@ -0,0 +1,57 @@
+# no-icon-file-extension-in-template-icon-name
+
+> **Rule catalog ID:** R063
+
+## Targeted pattern scope
+
+`iconName` in workflow-template properties metadata.
+
+## What this rule reports
+
+Reports `iconName` values ending in `.svg`.
+
+## Why this rule exists
+
+Template icon names should be bare icon identifiers, not filenames with extensions.
+
+## ❌ Incorrect
+
+```json
+{ "iconName": "workflow.svg" }
+```
+
+## ✅ Correct
+
+```json
+{ "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/no-icon-file-extension-in-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/no-inherit-secrets.md

@@ -0,0 +1,65 @@
+# no-inherit-secrets
+
+> **Rule catalog ID:** R026
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that call reusable workflows with `jobs.<job_id>.uses`.
+
+## What this rule reports
+
+This rule reports reusable-workflow jobs that use `secrets: inherit`.
+
+## Why this rule exists
+
+GitHub allows `secrets: inherit` to pass every secret available to the calling workflow into a directly called reusable workflow. Requiring explicitly named secrets keeps reusable-workflow integrations least-privileged and easier to review.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    secrets: inherit
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    secrets:
+      token: ${{ secrets.DEPLOY_TOKEN }}
+```
+
+
+## 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-inherit-secrets": "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_idsecretsinherit](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)
+- [https://docs.github.com/actions/using-workflows/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow](https://docs.github.com/actions/using-workflows/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow)

package/docs/rules/no-invalid-concurrency-context.md

@@ -0,0 +1,101 @@
+# no-invalid-concurrency-context
+
+> **Rule catalog ID:** R042
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define workflow-level `concurrency` or `jobs.<job_id>.concurrency` expressions.
+
+## What this rule reports
+
+This rule reports concurrency expressions that reference contexts GitHub does not allow at that location.
+
+- Top-level `concurrency` may only reference `github`, `inputs`, and `vars`
+- Job-level `concurrency` may only reference `github`, `needs`, `strategy`, `matrix`, `inputs`, and `vars`
+
+## Why this rule exists
+
+Concurrency is evaluated before steps run, so step-only and runner-time contexts such as `steps`, `secrets`, `env`, `job`, or `runner` are not available there. Using unsupported contexts makes concurrency groups invalid and can break workflow scheduling behavior.
+
+## ❌ Incorrect
+
+```yaml
+concurrency:
+  group: deploy-${{ secrets.ENVIRONMENT }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: deploy-${{ steps.meta.outputs.lock }}
+    steps:
+      - id: meta
+        run: echo "lock=prod" >> "$GITHUB_OUTPUT"
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Deployment target
+        required: true
+        type: string
+
+concurrency:
+  group: deploy-${{ github.workflow }}-${{ inputs.environment }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      lock: ${{ steps.meta.outputs.lock }}
+    steps:
+      - id: meta
+        run: echo "lock=prod" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    concurrency:
+      group: deploy-${{ needs.build.outputs.lock }}
+      cancel-in-progress: ${{ inputs.environment == 'prod' }}
+    steps:
+      - run: echo "Deploying"
+```
+
+
+## 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-invalid-concurrency-context": "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)
+- [https://docs.github.com/actions/reference/workflows-and-actions/contexts#context-availability](https://docs.github.com/actions/reference/workflows-and-actions/contexts#context-availability)

package/docs/rules/no-invalid-key.md

@@ -0,0 +1,86 @@
+# no-invalid-key
+
+> **Rule catalog ID:** R019
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML mappings at the top level and within common job substructures.
+
+## What this rule reports
+
+This rule reports unsupported keys in workflow mappings such as the top-level workflow object, jobs, steps, strategy blocks, containers, and services.
+
+## Why this rule exists
+
+Misspelled or misplaced workflow keys are easy to overlook in review and can silently break automation intent. Catching them early helps keep workflow files valid and easier to maintain.
+
+This rule focuses on common GitHub Actions workflow structures, including top-level workflow keys, jobs, strategy blocks, containers, services, and individual steps.
+
+## ❌ Incorrect
+
+```yaml
+name: CI
+on:
+  push:
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+      retry: 2
+    steps:
+      - name: Test
+        runs: npm test
+```
+
+## ✅ Correct
+
+```yaml
+name: CI
+on:
+  push:
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+    steps:
+      - name: Test
+        run: npm test
+```
+
+## Behavior and migration notes
+
+This rule validates keys in the most common workflow mappings where misspellings usually become hard-to-debug failures. It does not try to validate free-form maps such as `env`, `with`, `outputs`, or `secrets`, where user-defined keys are expected.
+
+
+## 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-invalid-key": "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](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax)
+- [https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow](https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow)

package/docs/rules/no-invalid-reusable-workflow-job-key.md

@@ -0,0 +1,74 @@
+# no-invalid-reusable-workflow-job-key
+
+> **Rule catalog ID:** R041
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML jobs that call reusable workflows via `jobs.<job_id>.uses`.
+
+## What this rule reports
+
+This rule reports unsupported keys on reusable-workflow caller jobs, such as `runs-on`, `steps`, `container`, `outputs`, `timeout-minutes`, or `environment`.
+
+## Why this rule exists
+
+Jobs that call reusable workflows have a much narrower supported keyword set than normal inline jobs. GitHub only allows caller-job keys such as `name`, `uses`, `with`, `secrets`, `strategy`, `needs`, `if`, `concurrency`, and `permissions`. Adding inline-job keys beside `uses` creates invalid workflow structure and confuses reviewers about where the real job logic lives.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "This caller job is invalid"
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  deploy:
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: production
+    secrets:
+      token: ${{ secrets.DEPLOY_TOKEN }}
+    permissions:
+      contents: read
+    concurrency:
+      group: deploy-${{ 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/no-invalid-reusable-workflow-job-key": "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/reusable-workflows-reference#supported-keywords-for-jobs-that-call-a-reusable-workflow](https://docs.github.com/actions/reference/reusable-workflows-reference#supported-keywords-for-jobs-that-call-a-reusable-workflow)
+- [https://docs.github.com/actions/using-workflows/reusing-workflows](https://docs.github.com/actions/using-workflows/reusing-workflows)

package/docs/rules/no-invalid-template-file-pattern-regex.md

@@ -0,0 +1,57 @@
+# no-invalid-template-file-pattern-regex
+
+> **Rule catalog ID:** R059
+
+## Targeted pattern scope
+
+`filePatterns` entries in workflow-template properties metadata.
+
+## What this rule reports
+
+Reports regex strings that are syntactically invalid.
+
+## Why this rule exists
+
+Invalid regex values break template recommendation matching.
+
+## ❌ Incorrect
+
+```json
+{ "filePatterns": ["(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-invalid-template-file-pattern-regex": "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://www.schemastore.org/github-workflow-template-properties.json](https://www.schemastore.org/github-workflow-template-properties.json)

package/docs/rules/no-invalid-workflow-call-output-value.md

@@ -0,0 +1,80 @@
+# no-invalid-workflow-call-output-value
+
+> **Rule catalog ID:** R040
+
+## Targeted pattern scope
+
+GitHub Actions workflow YAML files that define reusable workflow output values under `on.workflow_call.outputs.*.value`.
+
+## What this rule reports
+
+This rule reports reusable workflow output values that:
+
+- reference contexts that are not available in `on.workflow_call.outputs.*.value`
+- fail to map from a job output such as `jobs.build.outputs.artifact`
+
+## Why this rule exists
+
+GitHub only allows the `github`, `jobs`, `vars`, and `inputs` contexts when computing reusable workflow output values, and those values must ultimately come from a job output inside the called workflow. Direct `steps.*`, `needs.*`, `matrix.*`, or literal-only mappings are invalid and break the reusable workflow contract.
+
+## ❌ Incorrect
+
+```yaml
+on:
+  workflow_call:
+    outputs:
+      deployment-url:
+        description: Published deployment URL
+        value: ${{ steps.publish.outputs.url }}
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  workflow_call:
+    outputs:
+      deployment-url:
+        description: Published deployment URL
+        value: ${{ jobs.deploy.outputs.deployment-url }}
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    outputs:
+      deployment-url: ${{ steps.publish.outputs.url }}
+    steps:
+      - id: publish
+        run: echo "url=https://example.com" >> "$GITHUB_OUTPUT"
+```
+
+
+## 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-invalid-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/contexts#context-availability](https://docs.github.com/actions/reference/workflows-and-actions/contexts#context-availability)
+- [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-path-separators-in-template-icon-name.md

@@ -0,0 +1,57 @@
+# no-path-separators-in-template-icon-name
+
+> **Rule catalog ID:** R064
+
+## Targeted pattern scope
+
+`iconName` in workflow-template properties metadata.
+
+## What this rule reports
+
+Reports `iconName` values containing `/` or `\\`.
+
+## Why this rule exists
+
+`iconName` should be a token, not a filesystem path.
+
+## ❌ Incorrect
+
+```json
+{ "iconName": "icons/workflow" }
+```
+
+## ✅ Correct
+
+```json
+{ "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/no-path-separators-in-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://www.schemastore.org/github-workflow-template-properties.json](https://www.schemastore.org/github-workflow-template-properties.json)