JSON and SARIF integration¶

Single-project and portfolio reports use separate versioned JSON contracts so portfolio support does not silently change the existing single-project schema.

Single-project JSON¶

Single-project JSON remains deterministic and uses:

{
  "schema_version": "1.1",
  "tool": {
    "name": "gitlab-project-audit",
    "version": "0.1.0"
  },
  "summary": {
    "total": 1,
    "passed": 0,
    "failed": 1,
    "not_applicable": 0,
    "errors": 0
  },
  "findings": []
}

Generate it with:

gitlab-project-audit audit group/project --format json --output audit.json

Portfolio JSON¶

Multi-project and group audits return a separate portfolio document:

{
  "kind": "portfolio",
  "schema_version": "1.0",
  "summary": {
    "projects": 2,
    "project_errors": 0,
    "findings": 94,
    "passed": 80,
    "failed": 4,
    "not_applicable": 10,
    "errors": 0
  },
  "projects": [
    {
      "project": "group/project-a",
      "status": "completed",
      "error_message": null,
      "summary": {},
      "findings": []
    }
  ]
}

Examples:

gitlab-project-audit audit group/project-a group/project-b --format json
gitlab-project-audit audit --group group --format json --output portfolio.json

Project-level execution errors remain explicit in the projects array rather than disappearing from aggregate counts.

SARIF¶

Both single-project and portfolio audits support SARIF 2.1.0:

gitlab-project-audit audit group/project --format sarif --output audit.sarif
gitlab-project-audit audit --group group --format sarif --output portfolio.sarif

Portfolio SARIF preserves project identity in each result's properties. A project that cannot be audited is represented by the synthetic rule ID portfolio.project-execution.

Severity mapping:

Audit severity	SARIF level
`critical`, `high`	`error`
`medium`	`warning`
`low`, `info`	`note`
Rule/project execution error	`error`

Suppression state, reason, and expiry remain available in SARIF properties.

CI policy¶

--fail-on applies consistently to completed projects in a portfolio. Any project execution error returns exit code 3; otherwise an unsuppressed failed finding at/above the configured threshold returns exit code 1.

Published JSON Schemas¶

Machine-readable formats are backed by packaged Draft 2020-12 schemas:

Contract	Version	Resource
Configuration	1.0	`config-1.0.schema.json`
Single-project JSON report	1.1	`report-1.1.schema.json`
Portfolio JSON report	1.1	`portfolio-1.1.schema.json`
Audit baseline	1.1	`baseline-1.1.schema.json`
Baseline diff	1.0	`diff-1.0.schema.json`
Portfolio baseline	1.1	`portfolio-baseline-1.1.schema.json`
Portfolio baseline diff	1.0	`portfolio-diff-1.0.schema.json`
Portfolio snapshot	1.1	`portfolio-snapshot-1.1.schema.json`

Schema versioning is explicit. A breaking contract change requires a new resource/version rather than silently changing an existing 1.0 schema.

Provenance and reproducibility¶

Provenance-aware contracts use schema version 1.1. The existing 1.0 schema files remain packaged for historical consumers.

Machine-readable audit output records:

target project/path
GitLab instance URL
package version
effective rule-set SHA-256 fingerprint
effective policy SHA-256 fingerprint
audited default branch/ref when it was available without an extra API request

Rule-set and policy fingerprints are generated from canonical JSON representations. Equivalent ordering therefore produces the same fingerprint.

Provenance deliberately excludes authentication tokens, request headers, CI/CD variable values, and raw GitLab response bodies.

GitLab Code Quality¶

The codequality format emits GitLab's native Code Quality JSON array:

gitlab-project-audit audit group/project \
  --format codequality \
  --output gl-code-quality-report.json

Portfolio audits use the same format:

gitlab-project-audit audit group/a group/b \
  --format codequality \
  --output gl-code-quality-report.json

Only active fail and rule-execution error findings are emitted. Passed, not-applicable, and suppressed findings are omitted from active Code Quality degradations.

Fingerprints are stable SHA-256 digests of the project identity plus stable rule ID. This keeps the same rule distinct across projects in portfolio reports.

Severity mapping:

Audit severity/status	GitLab Code Quality severity
`info`	`info`
`low`	`minor`
`medium`	`major`
`high`	`critical`
`critical`	`blocker`
Rule/project execution error	`blocker`

A GitLab CI job can publish the generated file as a Code Quality report:

audit:
  script:
    - gitlab-project-audit audit "$CI_PROJECT_PATH" --format codequality --output gl-code-quality-report.json
  artifacts:
    reports:
      codequality: gl-code-quality-report.json