Skip to content

Installation and authentication

Requirements

  • Python 3.12 or newer
  • Poetry 2.x
  • GitLab.com or a reachable self-managed GitLab instance

Development installation

git clone https://gitlab.com/DiogoRibeiro7/gitlab-project-audit.git
cd gitlab-project-audit
poetry install

Confirm the CLI is available:

poetry run gitlab-project-audit --help

Authentication

The API client reads two environment variables:

Variable Required Meaning
GITLAB_TOKEN For private/permissioned data GitLab access token used as PRIVATE-TOKEN.
GITLAB_URL No Base URL for GitLab. Defaults to https://gitlab.com.

Example:

export GITLAB_TOKEN="..."
export GITLAB_URL="https://gitlab.com"

For a self-managed instance:

export GITLAB_URL="https://gitlab.example.org"

Do not commit access tokens

Keep real tokens out of repository files, fixtures, issue descriptions, logs, and screenshots.

Permissions

Different checks require different API permissions. A restricted endpoint is represented as unavailable or not applicable instead of being converted into a false failed finding.

In particular, approval rules and CI/CD variable metadata may depend on the current token's access and on the GitLab tier/instance configuration.

Diagnose connectivity and permissions

Run:

gitlab-project-audit doctor

This checks the configured GitLab instance and authentication without printing token material.

To diagnose one project as well:

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

Machine-readable output is available with:

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

Project diagnostics classify the following capability families independently:

  • project metadata
  • CI configuration access
  • CI/CD variables
  • pipeline history
  • releases

Possible statuses include ok, unauthenticated, permission_limited, not_found, unsupported, unavailable, and not_checked.