diff --git a/src/content/docs/cli/ci-cd/granular-actions.md b/src/content/docs/cli/ci-cd/granular-actions.md index cdc67330..a7564ee6 100644 --- a/src/content/docs/cli/ci-cd/granular-actions.md +++ b/src/content/docs/cli/ci-cd/granular-actions.md @@ -109,6 +109,8 @@ rules: A scanner with no gate reports and never fails its job. There is no baseline, so turn a gate on once a run is clean at that level. -On a pull request the rendered jobs do not spend the repository's GitHub API quota. Every scanner step gets `github-token: ${{ github.event_name != 'pull_request' && github.token || '' }}`, so a pull-request scan runs without the job token and does not resolve unknown licences through the GitHub API, and the `analyze` job adds `--no-forge`, so it skips the pass that reads every pull request and issue. That quota is shared with every other job in the repository, CodeQL's SARIF upload among them, and a large repository's scans used to spend it in minutes. The push to the default branch keeps the token and the forge pass, and is the run that publishes. +On a pull request the rendered jobs do not spend the repository's GitHub API quota. Every scanner step gets `github-token: ${{ github.event_name != 'pull_request' && github.token || '' }}`, so a pull-request scan runs without the job token and does not resolve unknown licences through the GitHub API, and the `analyze` job adds `--no-forge`, so it skips the pass that reads every pull request and issue. That quota is shared with every other job in the repository, CodeQL's SARIF upload among them, and a large repository's scans used to spend it in minutes. The push to the default branch keeps the token and is the run that publishes. + +The forge pass is bounded on every other run too. On a push or a release the `analyze` job passes `--forge-window-days=7`, so it reads only the last week of pull requests, issues and commit reviews from GitHub. The git history window stays at a year. Only a manual run (`workflow_dispatch`) reads the full window from GitHub. Whatever the window, `analyze` stops the forge pass while half the token's hourly limit is still left, and the report carries a warning when it stopped early. A push lands on every merge, and an auto-versioned repository publishes a release on every merge too. A year-long forge pass on each of them used to spend the repository's quota until CodeQL's upload and the release dispatch failed with `API rate limit exceeded for installation`. `vulnetix gha init --check` writes nothing and exits 1 when the workflow differs from what the policy renders. It ignores action refs, so a [locked](/cli/ci-cd/actions-lockfile/) workflow stays current. diff --git a/src/content/docs/cli/commands/analyze.md b/src/content/docs/cli/commands/analyze.md index 6b55abe3..20d873c5 100644 --- a/src/content/docs/cli/commands/analyze.md +++ b/src/content/docs/cli/commands/analyze.md @@ -30,6 +30,8 @@ On success it prints, for example, `GitHub authentication: ok (octocat via gh CL `--no-forge` skips GitHub: those metrics are then `not measured`. A repository whose remote is not GitHub skips the check by itself. +**The GitHub quota is shared.** In GitHub Actions, the job token's hourly quota belongs to the whole repository, and every job shares it. So `analyze` stops reading from GitHub while half the token's hourly limit is still left (never less than 100 requests). When that happens, the report carries a `forge` warning saying so. Each pull request costs several requests. `--forge-window-days` reads a shorter window from GitHub than `--window-days` reads from git, so the run makes fewer requests. + **A clone or a worktree.** Both work: a worktree's history is read from the main repository's git directory, so history metrics match the main checkout. A shallow clone has less history; increase the fetch depth for the window you want. **Vulnetix credentials (optional).** Dependency staleness needs registry metadata from Vulnetix. Without credentials those metrics are `null` with a reason, and the report is not uploaded. @@ -40,6 +42,7 @@ On success it prints, for example, `GitHub authentication: ok (octocat via gh CL |---|---|---| | `[path]`, `--path ` | `.` | Repository to analyse. The positional argument wins. | | `--window-days ` | `365` | How far back to walk history | +| `--forge-window-days ` | `0` (same as `--window-days`) | How far back to read pull requests, issues and commit reviews from GitHub | | `--max-commits ` | `20000` | Cap on commits walked; the report says when it was hit | | `--complexity-threshold ` | `15` | Cyclomatic complexity at which a file counts as highly complex | | `--no-git` | off | Skip the history walk: activity, contributor and ownership metrics are absent |