Skip to content

CLI

Commands

doctor

Diagnose GitLab connectivity and authentication:

gitlab-project-audit doctor

Optionally inspect project-level audit capability access:

gitlab-project-audit doctor --project group/project
gitlab-project-audit doctor --project group/project --json

The command never prints access-token material or raw GitLab error bodies. Core connectivity or authentication failure returns exit code 3. Permission-limited optional project capabilities are reported individually without making the core diagnostic unhealthy.

audit

Audit one project:

gitlab-project-audit audit group/project

Audit multiple explicit projects:

gitlab-project-audit audit group/project-a group/project-b --workers 4

Audit all accessible projects in a GitLab group and its subgroups:

gitlab-project-audit audit --group group
gitlab-project-audit audit --group group --include-archived --workers 4

Filter group projects before audit execution:

gitlab-project-audit audit --group group \
  --include-project "group/**" \
  --exclude-project "group/archive/*" \
  --topic python \
  --topic backend \
  --visibility private

Selection rules are deterministic:

  • repeated --include-project globs are OR-ed
  • --exclude-project always wins over include matches
  • repeated --topic values are AND-ed
  • repeated --visibility values are OR-ed
  • archived projects still require --include-archived

Inspect the selected projects without auditing:

gitlab-project-audit audit --group group \
  --include-project "group/**" \
  --topic python \
  --dry-run

Explicit project targets and --group are mutually exclusive. --include-archived applies only to group discovery. Portfolio concurrency defaults to four workers and is bounded to the range 1–32.

Single-project audits support:

  • human
  • json
  • sarif

Portfolio audits support the same three output choices as single-project audits: human, json, and sarif. Portfolio machine-readable formats use separate contracts so existing single-project schemas remain backward compatible.

Shared options:

--config PATH
--preset {minimal,team,strict}
--output PATH
--fail-on {info,low,medium,high,critical}
--request-budget N
--save-baseline PATH
--baseline PATH
--diff-output PATH
--fail-on-new
--save-snapshot PATH
--snapshot PATH

Single-project examples:

gitlab-project-audit audit group/project --format human
gitlab-project-audit audit group/project --format json --output audit.json
gitlab-project-audit audit group/project --format sarif --output audit.sarif
gitlab-project-audit audit group/project --fail-on high

Baseline and snapshot options support both single-project and portfolio audits. Single-project and portfolio modes use separate versioned contracts. See Baselines and regression diffs and Offline audit snapshots.

Portfolio output preserves deterministic project ordering, continues after an individual project fails, and applies the same --fail-on policy to completed projects. A project execution error returns exit code 3.

list-presets

Inspect built-in versioned starter policies:

gitlab-project-audit list-presets
gitlab-project-audit list-presets --json

See Policy presets for rule sets and precedence.

Validate a configuration file and print its effective JSON representation:

gitlab-project-audit print-effective-config
gitlab-project-audit print-effective-config --config policy.yml
gitlab-project-audit print-effective-config --fail-on high
gitlab-project-audit print-effective-config --preset strict

CLI options take precedence over values loaded from the configuration file.

The output also includes a validation section showing:

  • registered rule/category counts
  • referenced rule count
  • active suppressions
  • expired suppressions

Unknown rule/category references fail before any GitLab API access.

Exit codes

Code Meaning
0 Completed without a failed finding at/above the threshold.
1 At least one unsuppressed failed finding met the threshold.
2 CLI/configuration error.
3 Audit/rule/project execution error.

The default fail_on severity is medium.

Portfolio request budgets and rate limits

Portfolio audits can set a hard ceiling on GitLab HTTP attempts:

gitlab-project-audit audit --group group \
  --workers 8 \
  --request-budget 500

Every real HTTP attempt counts, including retry attempts. When the budget is exhausted, no further request is sent. Completed projects remain in the result and remaining/uncompleted projects are reported explicitly as errors, so the portfolio is never presented as a clean complete audit.

Portfolio execution also records GitLab rate-limit headers when available. Concurrency is recalculated between project batches and can fall below --workers when remaining quota is low or a 429 response has been observed.

Human and JSON portfolio reports expose:

  • observed request count
  • configured request budget
  • whether the budget was exhausted
  • latest rate-limit remaining/limit values
  • number of observed 429 responses
  • configured and recommended worker counts
  • whether execution is incomplete

GitLab Retry-After handling remains centralized in the API client and uses the existing bounded retry policy.