Reusable GitLab CI component¶

gitlab-project-audit ships a reusable GitLab CI/CD component in:

templates/audit.yml

The component runs the released OCI image and exposes typed inputs for policy, report format, baseline comparison, and artifact paths.

Versioning model¶

Use an exact release tag when including the component:

include:
  - component: $CI_SERVER_FQDN/DiogoRibeiro7/gitlab-project-audit/audit@v0.1.0

The component uses its own exact component.reference as the OCI image tag:

registry.gitlab.com/DiogoRibeiro7/gitlab-project-audit:v0.1.0

This means the component YAML and the runtime image come from the same project release.

Do not use a branch, commit SHA, partial version, or ~latest with this component. The OCI image publisher creates immutable exact release tags only.

Minimal consumer¶

include:
  - component: $CI_SERVER_FQDN/DiogoRibeiro7/gitlab-project-audit/audit@v0.1.0
    inputs:
      preset: team
      fail_on: high
      output_format: codequality
      output_path: gl-code-quality-report.json

The default target is $CI_PROJECT_PATH.

For codequality, the generated file is automatically declared as:

artifacts:
  reports:
    codequality: gl-code-quality-report.json

JSON and SARIF outputs are uploaded as ordinary downloadable artifacts.

Inputs¶

Input	Default	Notes
`job_name`	`gitlab-project-audit`	Prefix for the selected job.
`stage`	`test`	Consumer pipeline stage.
`target`	`$CI_PROJECT_PATH`	Project path/ID to audit.
`preset`	empty	Empty, `minimal`, `team`, or `strict`.
`config_path`	`.gitlab-project-audit.yml`	Policy config path.
`fail_on`	`medium`	`info` through `critical`.
`output_format`	`codequality`	`json`, `sarif`, or `codequality`.
`output_path`	`gl-code-quality-report.json`	Artifact path.
`baseline_mode`	`none`	`none` or `compare`.
`baseline_path`	`.gitlab-project-audit-baseline.json`	Baseline file for comparison.
`fail_on_new`	`false`	Requires `baseline_mode: compare`.

Baseline regression mode¶

If the repository contains a baseline:

include:
  - component: $CI_SERVER_FQDN/DiogoRibeiro7/gitlab-project-audit/audit@v0.1.0
    inputs:
      output_format: json
      output_path: audit.json
      baseline_mode: compare
      baseline_path: .gitlab-project-audit-baseline.json
      fail_on_new: true

The component intentionally does not create/update baselines. Baseline generation remains an explicit repository-maintenance action.

Self-audit example¶

This repository can consume the same public component path:

include:
  - component: $CI_SERVER_FQDN/DiogoRibeiro7/gitlab-project-audit/audit@v0.1.0
    inputs:
      job_name: self-audit
      target: DiogoRibeiro7/gitlab-project-audit
      config_path: .gitlab-project-audit.self.yml
      fail_on: critical
      output_format: json
      output_path: self-audit.json
      baseline_mode: compare
      baseline_path: .gitlab-project-audit.self-baseline.json
      fail_on_new: true

A copy-paste version is stored at examples/component-self-audit.yml.

Authentication¶

The component sets GITLAB_URL=$CI_SERVER_URL automatically.

For a complete audit of a private project, configure a masked/protected CI/CD variable named:

GITLAB_TOKEN

Prefer a project or group access token rather than a personal token when possible. The token should have the read_api scope and enough project permissions for the endpoints/rules you intend to audit.

The component does not need:

CI_REGISTRY_USER / CI_REGISTRY_PASSWORD
package publishing credentials
a personal publishing token

Those credentials are used only by this project's release pipeline, never by component consumers.

GitLab instance boundary¶

GitLab's include:component resolves components on the same GitLab instance as the consumer. This component is hosted on GitLab.com.

A self-managed GitLab consumer cannot directly use the GitLab.com component address through include:component. Self-managed users can mirror the component project/template on their own instance or run the published OCI image directly.

Output jobs¶

The component defines three format-specific jobs and uses typed input interpolation so exactly one is selected:

<job_name>-json
<job_name>-sarif
<job_name>-codequality

This avoids declaring a Code Quality report when the selected output is JSON or SARIF.

Testing¶

The repository structurally validates:

the component header and typed inputs
exact component-reference/image coupling
format routing
Code Quality report declaration
baseline argument assembly
consumer-instance configuration
absence of publishing credentials
exact release tags in examples

These tests run offline as part of the normal pytest suite.