eslint-plugin-github-actions-2 1.0.2 → 1.0.4

package/docs/rules/require-dependabot-schedule-interval.md

@@ -0,0 +1,66 @@
+# require-dependabot-schedule-interval
+
+> **Rule catalog ID:** R074
+
+## Targeted pattern scope
+
+`updates[*].schedule.interval` values in Dependabot configuration files, including values inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to a valid `schedule.interval` value.
+
+## Why this rule exists
+
+`schedule.interval` is a required Dependabot setting. Requiring a supported value keeps update frequency explicit and avoids accidental reliance on invalid or misspelled scheduling keys.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule: {}
+```
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "sometimes"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+This rule also accepts valid intervals inherited from `multi-ecosystem-groups`, so grouped configurations do not need to duplicate schedule frequency on every update block.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only when Dependabot files are not part of the lint surface for the repository.
+
+## Further reading
+
+- [Dependabot options reference: schedule](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#schedule-)
+- [Dependabot options reference: Required keys](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#required-keys)

package/docs/rules/require-dependabot-schedule-time.md

@@ -0,0 +1,60 @@
+# require-dependabot-schedule-time
+
+> **Rule catalog ID:** R075
+
+## Targeted pattern scope
+
+Non-`cron` schedule mappings in Dependabot update entries, including schedule settings inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports update entries that use a non-`cron` interval without declaring `schedule.time`.
+
+## Why this rule exists
+
+GitHub assigns a random execution time when `time` is omitted. Requiring an explicit time makes Dependabot activity predictable and easier to coordinate with release windows and CI load.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+```
+
+## Additional examples
+
+Repositories that want quieter daytime CI load often use this rule to keep Dependabot runs in an off-hours maintenance window.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if random Dependabot run times are acceptable for the repository.
+
+## Further reading
+
+- [Dependabot options reference: schedule.time](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#schedule-)
+- [Optimizing the creation of pull requests for Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates)

package/docs/rules/require-dependabot-schedule-timezone.md

@@ -0,0 +1,61 @@
+# require-dependabot-schedule-timezone
+
+> **Rule catalog ID:** R076
+
+## Targeted pattern scope
+
+Dependabot schedule mappings that use `time` or `cron` semantics, including values inherited from `multi-ecosystem-groups`.
+
+## What this rule reports
+
+This rule reports schedule blocks that require timezone context but omit `schedule.timezone`.
+
+## Why this rule exists
+
+Without a timezone, explicit times default to UTC. Requiring `timezone` makes scheduled runs match local operational intent instead of silently shifting around daylight saving or team-region assumptions.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "America/Detroit"
+```
+
+## Additional examples
+
+When teams operate outside UTC, this rule prevents silent schedule drift caused by assuming everyone reads `time` values in the same timezone.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally standardizes all Dependabot schedules on implicit UTC.
+
+## Further reading
+
+- [Dependabot options reference: schedule.timezone](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#schedule-)
+- [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

package/docs/rules/require-dependabot-target-branch.md

@@ -0,0 +1,63 @@
+# require-dependabot-target-branch
+
+> **Rule catalog ID:** R078
+
+## Targeted pattern scope
+
+Dependabot update entries and multi-ecosystem groups that decide where version-update pull requests land.
+
+## What this rule reports
+
+This rule reports update entries that do not resolve to a non-empty `target-branch`.
+
+## Why this rule exists
+
+Repositories with release trains or stabilization branches often want Dependabot changes routed predictably. Requiring `target-branch` removes ambiguity and documents the intended update flow directly in configuration.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      time: "05:30"
+      timezone: "UTC"
+    target-branch: "main"
+```
+
+## Additional examples
+
+This rule is most useful in repositories that validate dependency updates on a dedicated integration branch before merging into the default branch.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally wants Dependabot to always use the default branch implicitly.
+
+## Further reading
+
+- [Dependabot options reference: target-branch](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#target-branch-)
+- [Customizing Dependabot pull requests: Targeting pull requests against a non-default branch](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#targeting-pull-requests-against-a-non-default-branch)

package/docs/rules/require-dependabot-updates.md

@@ -0,0 +1,58 @@
+# require-dependabot-updates
+
+> **Rule catalog ID:** R071
+
+## Targeted pattern scope
+
+Repository Dependabot configuration files at `.github/dependabot.yml` or `.github/dependabot.yaml`.
+
+## What this rule reports
+
+This rule reports files that omit the top-level `updates` key or define it as an empty sequence.
+
+## Why this rule exists
+
+`updates` is the section where Dependabot is told which ecosystems to maintain. Without at least one update entry, the configuration is syntactically present but operationally useless.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+```
+
+```yaml
+version: 2
+updates: []
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+On repositories with multiple ecosystems, this rule helps ensure Dependabot stays enabled even after refactors remove one update block and forget to add its replacement.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only when `.github/dependabot.yml` is intentionally not used in the repository.
+
+## Further reading
+
+- [Dependabot options reference: Required keys](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#required-keys)
+- [Example dependabot.yml file](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-version-updates#example-dependabotyml-file)

package/docs/rules/require-dependabot-version.md

@@ -0,0 +1,70 @@
+# require-dependabot-version
+
+> **Rule catalog ID:** R070
+
+## Targeted pattern scope
+
+Repository Dependabot configuration files at `.github/dependabot.yml` or `.github/dependabot.yaml`.
+
+## What this rule reports
+
+This rule reports Dependabot configuration files that omit the top-level `version` key or set it to anything other than `2`.
+
+## Why this rule exists
+
+Dependabot configuration files must use schema version `2`. Omitting the key or using a different value makes the file invalid and prevents Dependabot from interpreting later settings reliably.
+
+## ❌ Incorrect
+
+```yaml
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+```yaml
+version: 1
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## Behavior and migration notes
+
+The autofixer inserts `version: 2` when the top-level key is missing and rewrites any other version value to `2`. That fix is safe because Dependabot configuration currently requires schema version 2.
+
+## Additional examples
+
+This rule pairs well with `require-dependabot-updates` so the file always declares both the schema version and at least one update block.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule only if you do not lint Dependabot configuration files with this plugin.
+
+## Further reading
+
+- [Dependabot options reference: Required keys](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#required-keys)
+- [Configuring Dependabot version updates](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configuring-dependabot-version-updates)

package/docs/rules/require-dependabot-versioning-strategy-for-npm.md

@@ -0,0 +1,58 @@
+# require-dependabot-versioning-strategy-for-npm
+
+> **Rule catalog ID:** R088
+
+## Targeted pattern scope
+
+Dependabot update entries with `package-ecosystem: "npm"`.
+
+## What this rule reports
+
+This rule reports npm update entries that omit `versioning-strategy`.
+
+## Why this rule exists
+
+`versioning-strategy` changes how Dependabot edits package manifests and lockfiles. Requiring the key makes npm range update behavior explicit, which is especially useful in monorepos and libraries with stricter dependency policies.
+
+## ❌ Incorrect
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+## ✅ Correct
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    versioning-strategy: "increase"
+    schedule:
+      interval: "weekly"
+```
+
+## Additional examples
+
+For application repositories, `increase` is a common choice because it keeps package ranges aligned with the updated resolved version.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.dependabot];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally accepts Dependabot's default versioning strategy heuristics for npm.
+
+## Further reading
+
+- [Dependabot options reference: versioning-strategy](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#versioning-strategy--)

package/docs/rules/require-dependency-review-action.md

@@ -0,0 +1,60 @@
+# require-dependency-review-action
+
+> **Rule catalog ID:** R091
+
+## Targeted pattern scope
+
+Workflow files whose path indicates a dependency review workflow, such as `.github/workflows/dependency-review.yml`.
+
+## What this rule reports
+
+This rule reports dependency review workflow files that do not invoke `actions/dependency-review-action`.
+
+## Why this rule exists
+
+If a workflow is intended to perform dependency review, it should actually run the dependency review action. Otherwise the workflow name and file path advertise security coverage that the repository is not really getting.
+
+## ❌ Incorrect
+
+```yaml
+name: "Dependency Review"
+on: [pull_request]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+```
+
+## ✅ Correct
+
+```yaml
+name: "Dependency Review"
+on: [pull_request]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/dependency-review-action@v4
+```
+
+## Additional examples
+
+This rule is file-path-driven, which keeps it precise without forcing every repository to adopt a global workflow-existence contract.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally uses a differently named workflow file or a reusable wrapper workflow for dependency review.
+
+## Further reading
+
+- [Customizing your dependency review action configuration](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-your-dependency-review-action-configuration)

package/docs/rules/require-dependency-review-fail-on-severity.md

@@ -0,0 +1,57 @@
+# require-dependency-review-fail-on-severity
+
+> **Rule catalog ID:** R093
+
+## Targeted pattern scope
+
+Workflow steps that use `actions/dependency-review-action`.
+
+## What this rule reports
+
+This rule reports dependency review action steps that omit `with.fail-on-severity`.
+
+## Why this rule exists
+
+Without an explicit severity threshold, the repository's vulnerability blocking posture is implicit. Requiring `fail-on-severity` makes that policy visible and reviewable in the workflow file.
+
+## ❌ Incorrect
+
+```yaml
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+```
+
+## ✅ Correct
+
+```yaml
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: moderate
+```
+
+## Additional examples
+
+Repositories commonly use `moderate` or stricter thresholds so dependency review blocks only meaningful risk while keeping pull request friction manageable.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if the repository intentionally accepts the action's default behavior and does not want to codify a severity threshold in workflow YAML.
+
+## Further reading
+
+- [Customizing your dependency review action configuration](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-your-dependency-review-action-configuration)

package/docs/rules/require-dependency-review-permissions-contents-read.md

@@ -0,0 +1,62 @@
+# require-dependency-review-permissions-contents-read
+
+> **Rule catalog ID:** R092
+
+## Targeted pattern scope
+
+Workflows that use `actions/dependency-review-action`.
+
+## What this rule reports
+
+This rule reports workflows using the dependency review action that do not set top-level `permissions.contents: read`.
+
+## Why this rule exists
+
+Dependency review only needs repository contents read access. Requiring that explicit least-privilege permission keeps security posture reviewable and prevents drift toward broader token scope.
+
+## ❌ Incorrect
+
+```yaml
+on: [pull_request]
+permissions:
+  contents: write
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+```
+
+## ✅ Correct
+
+```yaml
+on: [pull_request]
+permissions:
+  contents: read
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+```
+
+## Additional examples
+
+This rule complements `require-workflow-permissions` by enforcing the narrower security expectation specific to dependency review workflows.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule only if a repository-local wrapper around dependency review genuinely needs broader permissions and that design has already been reviewed.
+
+## Further reading
+
+- [Customizing your dependency review action configuration](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-your-dependency-review-action-configuration)
+- [GitHub Actions workflow syntax: permissions](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#permissions)

package/docs/rules/require-dependency-review-pull-request-trigger.md

@@ -0,0 +1,57 @@
+# require-dependency-review-pull-request-trigger
+
+> **Rule catalog ID:** R094
+
+## Targeted pattern scope
+
+Workflows that use `actions/dependency-review-action`.
+
+## What this rule reports
+
+This rule reports workflows using the dependency review action that do not listen for `pull_request`.
+
+## Why this rule exists
+
+Dependency review is designed to evaluate dependency changes introduced by pull requests. Requiring the `pull_request` trigger keeps the workflow aligned with that review surface.
+
+## ❌ Incorrect
+
+```yaml
+on: [workflow_dispatch]
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+```
+
+## ✅ Correct
+
+```yaml
+on: [pull_request]
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/dependency-review-action@v4
+```
+
+## Additional examples
+
+This rule does not prevent workflows from adding other triggers too. It only requires that `pull_request` be one of them when dependency review is present.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.security];
+```
+
+## When not to use it
+
+Disable this rule if the repository runs dependency review exclusively through a reusable workflow or another workflow trigger strategy.
+
+## Further reading
+
+- [Customizing your dependency review action configuration](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/customizing-your-dependency-review-action-configuration)