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

package/docs/rules/require-fetch-metadata-github-token.md

@@ -0,0 +1,49 @@
+# require-fetch-metadata-github-token
+
+> **Rule catalog ID:** R110
+
+## Targeted pattern scope
+
+Workflow steps that use `dependabot/fetch-metadata`.
+
+## What this rule reports
+
+This rule reports fetch-metadata steps that do not configure `with.github-token`.
+
+## Why this rule exists
+
+`dependabot/fetch-metadata` needs a token to retrieve pull request dependency metadata. Requiring the token input makes the workflow contract explicit and avoids subtle runtime failures.
+
+## ❌ Incorrect
+
+```yaml
+- uses: dependabot/fetch-metadata@v2
+```
+
+## ✅ Correct
+
+```yaml
+- uses: dependabot/fetch-metadata@v2
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Additional examples
+
+This rule only checks for the presence of a non-empty token input. It does not prescribe a specific secret name.
+
+## 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 the action changes to no longer require an explicit token input.
+
+## Further reading
+
+- [dependabot/fetch-metadata](https://github.com/dependabot/fetch-metadata)

package/docs/rules/require-job-name.md

@@ -31,6 +31,9 @@ jobs:
     runs-on: ubuntu-latest
 ```
 
+## Behavior and migration notes
+
+This rule provides a suggestion that uses the job ID as a fallback display name when `name` is missing or blank. That is useful for quick cleanup, but you should still review the suggestion and replace it with a more descriptive label when the job does more than the raw ID implies.
 
 ## Additional examples
 
@@ -57,7 +60,8 @@ export default [
 ## 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_idname](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
-- [https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow](https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow)
+- [GitHub Actions workflow syntax: `jobs.<job_id>.name`](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
+- [GitHub Actions docs: Using jobs in a workflow](https://docs.github.com/actions/using-jobs/using-jobs-in-a-workflow)

package/docs/rules/require-job-step-name.md

@@ -37,6 +37,14 @@ jobs:
         run: npm test
 ```
 
+## Behavior and migration notes
+
+This rule provides suggestions when it can infer a meaningful step label from existing step content:
+
+- for `uses:` steps, it suggests the action reference without the version suffix, and
+- for `run:` steps, it suggests the first non-empty command line when that line is short enough to read well in logs.
+
+Those suggestions are intentionally reviewable rather than automatically applied because human-friendly step names often need a little more context than the raw command or action reference.
 
 ## Additional examples
 
@@ -63,7 +71,8 @@ export default [
 ## 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_idsteps](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps)
-- [https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs)
+- [GitHub Actions workflow syntax: `jobs.<job_id>.steps`](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsteps)
+- [GitHub Actions docs: Using workflow run logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs)

package/docs/rules/require-sarif-upload-security-events-write.md

@@ -0,0 +1,50 @@
+# require-sarif-upload-security-events-write
+
+> **Rule catalog ID:** R102
+
+## Targeted pattern scope
+
+Jobs that use `github/codeql-action/upload-sarif`.
+
+## What this rule reports
+
+This rule reports SARIF upload jobs that do not grant `security-events: write`.
+
+## Why this rule exists
+
+Uploading SARIF to GitHub code scanning requires `security-events: write`. Requiring it explicitly keeps workflow permissions correct and reviewable.
+
+## ❌ Incorrect
+
+```yaml
+permissions:
+  contents: read
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+```
+
+## Additional examples
+
+This rule applies to any SARIF uploader step using `github/codeql-action/upload-sarif`, not just CodeQL-native workflows.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule only if the uploader step is never intended to publish SARIF into GitHub code scanning.
+
+## Further reading
+
+- [About code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

package/docs/rules/require-scorecard-results-format-sarif.md

@@ -0,0 +1,49 @@
+# require-scorecard-results-format-sarif
+
+> **Rule catalog ID:** R103
+
+## Targeted pattern scope
+
+Workflow steps that use `ossf/scorecard-action`.
+
+## What this rule reports
+
+This rule reports Scorecard action steps that do not set `results_format: sarif`.
+
+## Why this rule exists
+
+If a repository wants Scorecard findings to flow into GitHub code scanning, SARIF is the correct results format. Requiring it makes the upload contract explicit.
+
+## ❌ Incorrect
+
+```yaml
+- uses: ossf/scorecard-action@v2
+```
+
+## ✅ Correct
+
+```yaml
+- uses: ossf/scorecard-action@v2
+  with:
+    results_format: sarif
+```
+
+## Additional examples
+
+This rule pairs naturally with `require-scorecard-upload-sarif-step`, which ensures the generated SARIF is actually published.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if your Scorecard workflow intentionally produces non-SARIF output for another destination.
+
+## Further reading
+
+- [OpenSSF Scorecard Action](https://github.com/ossf/scorecard-action)

package/docs/rules/require-scorecard-upload-sarif-step.md

@@ -0,0 +1,55 @@
+# require-scorecard-upload-sarif-step
+
+> **Rule catalog ID:** R104
+
+## Targeted pattern scope
+
+Workflows that use `ossf/scorecard-action`.
+
+## What this rule reports
+
+This rule reports Scorecard workflows that do not upload SARIF results with `github/codeql-action/upload-sarif`.
+
+## Why this rule exists
+
+Generating SARIF without uploading it leaves the code scanning integration incomplete. Requiring the upload step helps repositories actually surface Scorecard findings in GitHub.
+
+## ❌ Incorrect
+
+```yaml
+- uses: ossf/scorecard-action@v2
+  with:
+    results_format: sarif
+```
+
+## ✅ Correct
+
+```yaml
+- uses: ossf/scorecard-action@v2
+  with:
+    results_format: sarif
+
+- uses: github/codeql-action/upload-sarif@v4
+  with:
+    sarif_file: results.sarif
+```
+
+## Additional examples
+
+This rule does not require a specific SARIF filename, only that an upload step exists.
+
+## ESLint flat config example
+
+```ts
+import githubActions from "eslint-plugin-github-actions-2";
+
+export default [githubActions.configs.codeScanning];
+```
+
+## When not to use it
+
+Disable this rule if SARIF upload is handled by a reusable workflow or another job outside the current file.
+
+## Further reading
+
+- [OpenSSF Scorecard Action](https://github.com/ossf/scorecard-action)

package/docs/rules/require-secret-scan-contents-read.md

@@ -0,0 +1,48 @@
+# require-secret-scan-contents-read
+
+> **Rule catalog ID:** R107
+
+## Targeted pattern scope
+
+Jobs that use supported secret-scanning actions.
+
+## What this rule reports
+
+This rule reports secret-scanning jobs that do not grant `contents: read`.
+
+## Why this rule exists
+
+Secret-scanning workflows generally only need read access to repository contents. Making that permission explicit reinforces least privilege.
+
+## ❌ Incorrect
+
+```yaml
+permissions: {}
+```
+
+## ✅ Correct
+
+```yaml
+permissions:
+  contents: read
+```
+
+## Additional examples
+
+This rule is intentionally narrow and does not try to prescribe every other permission a secret-scanning workflow may or may not need.
+
+## 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 your scanner workflow runs in an unusual environment that truly does not need repository contents access.
+
+## Further reading
+
+- [GitHub Actions workflow syntax: permissions](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#permissions)

package/docs/rules/require-secret-scan-fetch-depth-zero.md

@@ -0,0 +1,50 @@
+# require-secret-scan-fetch-depth-zero
+
+> **Rule catalog ID:** R105
+
+## Targeted pattern scope
+
+Jobs that use secret-scanning actions such as Gitleaks or TruffleHog.
+
+## What this rule reports
+
+This rule reports secret-scanning jobs that do not checkout repository history with `fetch-depth: 0`.
+
+## Why this rule exists
+
+Secret scanners are most effective when they can inspect full repository history rather than only the latest commit range.
+
+## ❌ Incorrect
+
+```yaml
+- uses: actions/checkout@v6
+```
+
+## ✅ Correct
+
+```yaml
+- uses: actions/checkout@v6
+  with:
+    fetch-depth: 0
+```
+
+## Additional examples
+
+This rule is job-scoped, so it only checks jobs that actually run the supported secret scanners.
+
+## 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 your secret scanning workflow is intentionally limited to shallow history or event-specific diffs.
+
+## Further reading
+
+- [Gitleaks Action](https://github.com/gitleaks/gitleaks-action)
+- [TruffleHog Action](https://github.com/trufflesecurity/trufflehog)

package/docs/rules/require-secret-scan-schedule.md

@@ -0,0 +1,50 @@
+# require-secret-scan-schedule
+
+> **Rule catalog ID:** R106
+
+## Targeted pattern scope
+
+Workflows that use supported secret-scanning actions.
+
+## What this rule reports
+
+This rule reports secret-scanning workflows that do not define a `schedule` trigger.
+
+## Why this rule exists
+
+Scheduled secret scanning catches leaks even when no recent pull request or push event happens on the affected branch.
+
+## ❌ Incorrect
+
+```yaml
+on: [pull_request]
+```
+
+## ✅ Correct
+
+```yaml
+on:
+  pull_request:
+  schedule:
+    - cron: "12 4 * * *"
+```
+
+## Additional examples
+
+This rule does not enforce a particular cron expression, only that periodic scanning exists.
+
+## 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 scheduled secret scanning is handled outside GitHub Actions.
+
+## Further reading
+
+- [GitHub Actions workflow syntax: schedule](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#onschedule)

package/docs/rules/require-trufflehog-verified-results-mode.md

@@ -0,0 +1,49 @@
+# require-trufflehog-verified-results-mode
+
+> **Rule catalog ID:** R108
+
+## Targeted pattern scope
+
+Workflow steps that use the TruffleHog GitHub Action.
+
+## What this rule reports
+
+This rule reports TruffleHog steps that do not configure `extra_args` to include `--results=verified`.
+
+## Why this rule exists
+
+Verified-results mode reduces noise by failing only on findings that the scanner can verify more confidently.
+
+## ❌ Incorrect
+
+```yaml
+- uses: trufflesecurity/trufflehog@v3
+```
+
+## ✅ Correct
+
+```yaml
+- uses: trufflesecurity/trufflehog@v3
+  with:
+    extra_args: --results=verified
+```
+
+## Additional examples
+
+This rule still allows additional TruffleHog flags as long as the verified-results mode 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 your repository intentionally wants broader TruffleHog results despite the extra noise.
+
+## Further reading
+
+- [TruffleHog Action](https://github.com/trufflesecurity/trufflehog)