Skip to content

Configuration

The default repository policy file is:

.gitlab-project-audit.yml

A complete example is included in the repository as .gitlab-project-audit.example.yml.

Precedence

  1. Built-in defaults
  2. Selected policy preset
  3. Configuration file
  4. Explicit CLI overrides

CLI values therefore win when the same option is supplied in both places.

See Policy presets for the built-in minimal, team, and strict profiles.

Fields

Preset

preset: team

Preset values are expanded before the rest of the configuration file is applied.

Category selection

enabled_categories:
  - project
  - governance

disabled_categories:
  - releases

When enabled_categories is non-empty, only those categories are selected before disabled categories are applied.

Rule selection

enabled_rules:
  - project.readme-present
  - governance.pipeline-required

disabled_rules:
  - project.contributing-present

Explicit disabled rules are removed after selection.

Severity overrides

severity_overrides:
  governance.pipeline-required: high
  project.license-present: info

Overrides change the finding severity before exit-code evaluation.

Suppressions

Suppressions require a reason and may have an expiry date:

suppressions:
  - rule: project.license-present
    reason: Internal-only repository; distribution is not planned.
    expires_on: 2027-01-31

A suppression does not delete the finding. The finding remains visible with:

  • suppressed: true
  • suppression reason
  • optional expiry date

Expired suppressions stop applying automatically. Active suppressions remain visible in reports but do not contribute to the --fail-on exit-code threshold.

Failure threshold

fail_on: medium

Valid values are info, low, medium, high, and critical.

Validation

Configuration is validated in two stages before network-heavy audit work.

Syntax and structure

YAML parsing and field-shape validation catch:

  • unknown top-level keys
  • invalid severity values
  • malformed suppression entries
  • invalid dates
  • fields with the wrong type

Semantic policy validation

After preset, file, and CLI precedence are resolved, the effective policy is checked against the canonical rule catalogue.

Semantic validation rejects:

  • unknown enabled/disabled rule IDs
  • unknown enabled/disabled categories
  • severity overrides for unknown rule IDs
  • suppressions for unknown rule IDs

These failures return configuration exit code 2 before a GitLab client is constructed.

Expired suppressions are not configuration errors. They are listed explicitly in print-effective-config, but they are not active and therefore do not suppress findings.

Use:

gitlab-project-audit print-effective-config

to inspect the resulting policy.

JSON Schema

The configuration contract is published as a packaged Draft 2020-12 JSON Schema:

config-1.0.schema.json

The version is independent from the Python package version. Backward-incompatible schema changes require a new schema version.

List packaged schemas with:

gitlab-project-audit schemas
gitlab-project-audit schemas --json