GitLab CI : audit, conformité et traçabilité des pipelines

La question d'un auditeur n'est jamais "est-ce que vous êtes sécurisés ?" mais "prouvez-le". GitLab enregistre des centaines de types d'événements d'audit : qui a modifié une branche protégée, qui a approuvé un déploiement, qui a changé les permissions d'un runner. Ce guide vous montre comment exploiter ces mécanismes pour répondre aux exigences SOC 2, ISO 27001 ou NIS2 avec des données concrètes.

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

Consulter les audit events de GitLab (projet, groupe, instance)
Requêter l'API d'audit pour extraire des événements précis
Mettre en place un compliance framework pour appliquer des politiques par projet
Configurer des compliance pipelines pour forcer l'exécution de jobs de sécurité
Streamer les événements vers un SIEM externe (Splunk, ELK, Datadog)

Dans quel contexte ?

L'audit et la conformité deviennent nécessaires quand :

Un auditeur externe (SOC 2, ISO 27001) demande la preuve que les déploiements suivent un processus de validation
Votre organisation est soumise à NIS2 et doit démontrer la traçabilité de sa chaîne logicielle
Un incident de sécurité survient et vous devez reconstituer qui a fait quoi, quand
Vous gérez des dizaines de projets et devez garantir que chacun applique les mêmes règles de sécurité
Des développeurs contournent les contrôles (désactivation d'une branche protégée, suppression d'une approbation) et vous devez le détecter

Audit events : ce que GitLab enregistre

Un audit event est une trace immuable écrite par GitLab à chaque action sensible : nul ne peut la modifier ni la supprimer depuis l'interface, ce qui en fait une preuve recevable. Ces événements ne concernent pas le code mais la configuration et les droits : qui a ouvert une branche protégée, qui a changé un secret, qui a ajouté un membre. Le périmètre visible dépend de votre rôle et du niveau auquel l'événement a été enregistré.

Les trois niveaux d'audit

GitLab enregistre des événements à trois niveaux :

Niveau	Visibilité	Exemples d'événements
Projet	Maintainer+	MR mergée, pipeline lancé, variable modifiée, branche protégée changée
Groupe	Owner	Membre ajouté/retiré, permission changée, runner partagé configuré
Instance	Admin	Utilisateur créé, 2FA désactivé, paramètre global modifié

Consulter les audit events

Deux chemins d'accès existent, et ils ne renvoient pas la même chose : l'interface propose un journal filtrable mais réservé à GitLab Premium, tandis que l'API REST reste disponible plus largement et se prête à l'automatisation. Le paramètre created_after attend une date au format AAAA-MM-JJ ; sans lui, l'API remonte les événements les plus récents seulement.

Interface
API

Projet : Settings → General → Audit events (GitLab Premium+).

Vous voyez un journal chronologique avec l'auteur, l'action et la cible.

# Audit events d'un projet (30 derniers jours)
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/audit_events?created_after=2026-03-16"

Résultat :

[
  {
    "id": 1234,
    "author_id": 42,
    "entity_id": 7,
    "entity_type": "Project",
    "details": {
      "change": "protected_branch",
      "from": "",
      "to": "main",
      "author_name": "Alice Martin",
      "target_details": "main",
      "custom_message": "Protected branch main: allowed to push changed from Developers + Maintainers to No one"
    },
    "created_at": "2026-03-20T14:32:00Z"
  }
]

Événements critiques à surveiller

GitLab enregistre plusieurs centaines de types d'événements, dont la majorité n'intéresse personne. Les neuf lignes ci-dessous sont celles qui signalent un affaiblissement des contrôles : elles précèdent presque toujours un contournement ou un incident. Ce sont les premières à câbler dans une alerte, avant de s'occuper du reste.

Événement	Pourquoi le surveiller	Catégorie
`protected_branch_created` / `removed`	Quelqu'un a modifié la politique de branches	Contrôle d'accès
`approval_rule_created` / `deleted`	Les règles d'approbation MR ont changé	Processus de validation
`environment_protected` / `unprotected`	L'environnement de production a perdu sa protection	Déploiement
`variable_created` / `updated` / `deleted`	Un secret CI a été modifié	Secrets
`runner_registration`	Un nouveau runner a été enregistré	Infrastructure
`member_added` / `removed`	Les permissions d'accès au projet ont changé	Contrôle d'accès
`deploy_key_added`	Une clé de déploiement a été ajoutée	Accès externe
`merge_request_approved`	Une MR a été approuvée (par qui ?)	Traçabilité
`pipeline_schedule_created`	Un pipeline planifié a été créé	Automatisation

Requêter l'API d'audit

L'interface montre un journal continu ; l'API permet de répondre à une question précise, datée et bornée. Toutes les requêtes qui suivent combinent un endpoint GitLab et un filtre jq, l'outil en ligne de commande qui découpe du JSON. Elles supposent deux variables d'environnement définies au préalable : GITLAB_URL et GITLAB_TOKEN.

Questions typiques d'un auditeur

Les auditeurs posent des questions précises. Voici comment y répondre avec l'API :

"Qui a modifié les branches protégées ce mois-ci ?"

curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/audit_events?created_after=2026-03-01" \
  | jq '[.[] | select(.details.change == "protected_branch")]
        | .[] | {date: .created_at, author: .details.author_name, action: .details.custom_message}'

"Qui a approuvé les MR déployées en production ?"

# Lister les MR mergées sur main ce mois
curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/merge_requests?state=merged&target_branch=main&updated_after=2026-03-01" \
  | jq '.[] | {iid: .iid, title: .title, merged_by: .merged_by.name, approved_by: [.approved_by[].user.name]}'

"Y a-t-il eu des déploiements pendant le freeze ?"

curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/deployments?environment=production&updated_after=2026-03-28&updated_before=2026-04-02" \
  | jq '.[] | {id: .id, created_at: .created_at, status: .status, deployed_by: .deployable.user.name}'

Script d'audit automatisé

Pour générer un rapport d'audit régulier :

#!/usr/bin/env bash
# audit-report.sh : rapport d'audit mensuel pour un projet GitLab
set -euo pipefail

PROJECT_ID="${1:?Usage: $0 <project_id>}"
SINCE=$(date -d "30 days ago" +%Y-%m-%d)
API="$GITLAB_URL/api/v4/projects/$PROJECT_ID"
AUTH="PRIVATE-TOKEN: $GITLAB_TOKEN"

echo "=== Rapport d'audit, projet $PROJECT_ID, depuis $SINCE ==="

echo ""
echo "--- Modifications de branches protégées ---"
curl -s -H "$AUTH" "$API/audit_events?created_after=$SINCE" \
  | jq -r '.[] | select(.details.change == "protected_branch")
           | "\(.created_at) | \(.details.author_name) | \(.details.custom_message)"'

echo ""
echo "--- Modifications de variables CI ---"
curl -s -H "$AUTH" "$API/audit_events?created_after=$SINCE" \
  | jq -r '.[] | select(.details.change == "ci_variable")
           | "\(.created_at) | \(.details.author_name) | \(.details.custom_message)"'

echo ""
echo "--- Déploiements en production ---"
curl -s -H "$AUTH" "$API/deployments?environment=production&updated_after=$SINCE" \
  | jq -r '.[] | "\(.created_at) | \(.deployable.user.name // "système") | \(.status) | ref:\(.ref)"'

echo ""
echo "--- MR mergées sur main ---"
curl -s -H "$AUTH" "$API/merge_requests?state=merged&target_branch=main&updated_after=$SINCE" \
  | jq -r '.[] | "!\(.iid) | \(.merged_at) | \(.merged_by.name) | \(.title)"'

Compliance frameworks

Les sections précédentes servaient à constater après coup. Un compliance framework sert à imposer en amont : c'est l'objet GitLab qui rattache un projet à une réglementation donnée et qui déclenche les contrôles associés. Cette fonctionnalité relève de l'édition Ultimate, avec des contournements partiels décrits plus bas pour les autres éditions.

Le mécanisme

Un compliance framework est un label appliqué à un projet pour indiquer qu'il est soumis à une politique spécifique. Il sert deux objectifs :

Visibilité : identifier rapidement quels projets sont soumis à quelle réglementation
Enforcement : attacher un compliance pipeline qui s'exécute automatiquement

Créer un compliance framework

Le framework se définit une seule fois au niveau du groupe, puis se rattache à autant de projets que nécessaire : il n'existe pas de framework de projet. Les trois étapes ci-dessous couvrent la création, le rattachement et la vérification par l'API, cette dernière étant le seul moyen fiable de contrôler en masse un parc de projets.

Créer le framework au niveau du groupe

Group → Settings → General → Compliance frameworks → New framework.

Champ Exemple
Name SOC 2, Production
Description Projets soumis aux contrôles SOC 2 Type II
Color #FF0000
Compliance pipeline URL du fichier .gitlab-ci.yml de conformité
Attacher le framework à un projet

Project → Settings → General → Compliance framework → sélectionner le framework.

Le label apparaît sur la page du projet et dans les listes de projets.

Champ	Exemple
Name	SOC 2, Production
Description	Projets soumis aux contrôles SOC 2 Type II
Color	#FF0000
Compliance pipeline	URL du fichier `.gitlab-ci.yml` de conformité

Vérifier via l'API

curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID" \
  | jq '.compliance_frameworks'

Résultat attendu :

["SOC 2, Production"]

Compliance pipelines

Le framework pose une étiquette ; le compliance pipeline est ce qui la rend contraignante. C'est un fichier de pipeline hébergé hors du projet, que GitLab exécute à la place de celui du dépôt, et sur lequel le développeur n'a aucun droit d'écriture. Cette inversion de contrôle est le seul mécanisme natif qui garantit qu'un job de sécurité tourne vraiment.

Le problème

Un développeur peut modifier ou supprimer les jobs de sécurité dans son .gitlab-ci.yml. Les includes partagés peuvent être commentés. Rien ne garantit que le scan de vulnérabilités s'exécute réellement.

La solution : compliance pipeline

Un compliance pipeline est un .gitlab-ci.yml maintenu par l'équipe sécurité, exécuté automatiquement sur tout projet attaché à un compliance framework. Le développeur ne peut pas le modifier ni le désactiver.

stages:
  - compliance-check
  - .pre
  - build
  - test
  - deploy
  - .post
  - compliance-report

# Ce job s'exécute AVANT le pipeline du développeur
compliance-secret-scan:
  stage: compliance-check
  image:
    name: ghcr.io/gitleaks/gitleaks:v8.30.1
    entrypoint: [""]
  script:
    - gitleaks detect --source . --verbose --exit-code 1
  allow_failure: false

# Ce job s'exécute APRÈS le pipeline du développeur
compliance-report:
  stage: compliance-report
  image: alpine:3.20
  script:
    - echo "Pipeline $CI_PIPELINE_ID, projet $CI_PROJECT_PATH"
    - echo "Commit $CI_COMMIT_SHA, auteur $GITLAB_USER_NAME"
    - echo "Branche $CI_COMMIT_BRANCH, ref $CI_COMMIT_REF_NAME"
    - echo "Compliance check passed at $(date -u)"
  artifacts:
    paths:
      - compliance-*.log
    expire_in: 1 year

Comment ça fonctionne

Le compliance pipeline remplace le pipeline du projet. Il utilise include: pour incorporer le .gitlab-ci.yml du développeur entre ses propres stages :

include:
  - project: '$CI_PROJECT_PATH'
    ref: '$CI_COMMIT_SHA'
    file: '.gitlab-ci.yml'

stages:
  - compliance-check
  - build
  - test
  - deploy
  - compliance-report

compliance-secret-scan:
  stage: compliance-check
  # ... (comme ci-dessus)

compliance-report:
  stage: compliance-report
  # ... (comme ci-dessus)

Le développeur garde la main sur ses stages build, test, deploy. L'équipe sécurité contrôle les stages compliance-check et compliance-report.

En GitLab CE, vous ne pouvez pas forcer un compliance pipeline. L'alternative est d'utiliser des include: dans chaque projet :

include:
  - project: 'security/compliance-templates'
    ref: v1.0.0
    file: 'security-jobs.yml'

Combinez avec un scan régulier (plumber, script API) pour vérifier que l'include est présent dans chaque .gitlab-ci.yml.

Streaming audit events

Consulter les audit events suppose que quelqu'un pense à aller les lire. Le streaming renverse la logique : GitLab pousse chaque événement, au fil de l'eau, vers un système externe. La cible habituelle est un SIEM (Security Information and Event Management), la plateforme qui centralise les journaux de sécurité de toute l'entreprise et déclenche les alertes.

Envoyer les événements vers un SIEM

Pour une surveillance continue, GitLab peut streamer les audit events vers une destination externe :

Configurer la destination

Group → Settings → General → Audit events → Streaming → Add streaming destination.

Champ Valeur
Destination URL https://siem.example.com/api/gitlab-events
Verification token Token partagé pour authentifier les requêtes

Champ	Valeur
Destination URL	`https://siem.example.com/api/gitlab-events`
Verification token	Token partagé pour authentifier les requêtes

Format des événements

GitLab envoie un POST HTTP avec un payload JSON pour chaque événement :

{
  "id": 5678,
  "author_id": 42,
  "entity_id": 7,
  "entity_type": "Project",
  "event_type": "audit_events",
  "details": {
    "change": "protected_branch",
    "from": "Developers + Maintainers",
    "to": "No one",
    "author_name": "Alice Martin",
    "target_details": "main"
  },
  "created_at": "2026-04-15T10:30:00Z"
}

Vérifier la réception

Utilisez un endpoint de test pour valider le flux :

# Lister les destinations de streaming
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/groups/$GROUP_ID/audit_events/streaming/destinations"

Destinations courantes

GitLab ne propose pas d'intégration dédiée par produit : il envoie un POST HTTP avec un corps JSON, à charge de la destination de l'accepter. Le tableau donne, pour les quatre plateformes les plus répandues, le point d'entrée qui sait recevoir ce format brut.

SIEM	Méthode	Configuration
Splunk	HTTP Event Collector	URL HEC + token
ELK / OpenSearch	Endpoint HTTP	Logstash HTTP input ou direct Elasticsearch
Datadog	HTTP Log endpoint	`https://http-intake.logs.datadoghq.eu/api/v2/logs` + API key
Google Chronicle	Webhook	Ingestion API endpoint

En GitLab CE, le streaming n'est pas disponible. Utilisez un cron job qui interroge l'API d'audit toutes les 5 minutes et pousse les nouveaux événements vers votre SIEM :

# Récupérer les événements des 10 dernières minutes
curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/audit_events?created_after=$(date -d '10 minutes ago' -Iseconds)" \
  | jq -c '.[]' \
  | while read -r event; do
      curl -s -X POST "$SIEM_URL" \
        -H "Content-Type: application/json" \
        -d "$event"
    done

Tableau de bord de conformité

Un auditeur demande un état, pas un journal. Le script qui suit interroge la configuration courante de chaque projet et la traduit en un score chiffré, reproductible d'un mois sur l'autre. Il ne dépend d'aucune édition payante : tous les endpoints utilisés sont disponibles en GitLab CE.

Construire un rapport de conformité projet

Combinez les données d'audit avec les informations de configuration pour produire un score de conformité :

#!/usr/bin/env bash
# compliance-score.sh : score de conformité d'un projet GitLab
set -euo pipefail

PROJECT_ID="${1:?Usage: $0 <project_id>}"
API="$GITLAB_URL/api/v4/projects/$PROJECT_ID"
AUTH="PRIVATE-TOKEN: $GITLAB_TOKEN"
score=0
total=0

check() {
  local label="$1" result="$2"
  total=$((total + 1))
  if [[ "$result" == "true" ]]; then
    score=$((score + 1))
    echo "  [OK] $label"
  else
    echo "  [KO] $label"
  fi
}

echo "=== Compliance score, projet $PROJECT_ID ==="

# Branche main protégée ?
main_protected=$(curl -s -H "$AUTH" "$API/protected_branches" \
  | jq 'any(.[]; .name == "main")')
check "Branche main protégée" "$main_protected"

# Force push interdit ?
no_force=$(curl -s -H "$AUTH" "$API/protected_branches" \
  | jq '[.[] | select(.name == "main")] | .[0].allow_force_push == false')
check "Force push interdit sur main" "$no_force"

# Tags protégés ?
tags_protected=$(curl -s -H "$AUTH" "$API/protected_tags" \
  | jq 'length > 0')
check "Tags protégés configurés" "$tags_protected"

# MR obligatoire sur main ?
no_push=$(curl -s -H "$AUTH" "$API/protected_branches" \
  | jq '[.[] | select(.name == "main")] | .[0].push_access_levels | any(.[]; .access_level == 0)')
check "Push direct interdit sur main" "$no_push"

# Approbation MR requise ?
approvals=$(curl -s -H "$AUTH" "$API/approval_rules" \
  | jq 'any(.[]; .approvals_required > 0)')
check "Approbation MR requise" "$approvals"

# Pipeline actif ?
has_pipeline=$(curl -s -H "$AUTH" "$API/pipelines?per_page=1&status=success" \
  | jq 'length > 0')
check "Pipeline CI actif" "$has_pipeline"

echo ""
echo "Score : $score / $total"

Résultat attendu :

=== Compliance score, projet 42 ===
  [OK] Branche main protégée
  [OK] Force push interdit sur main
  [KO] Tags protégés configurés
  [OK] Push direct interdit sur main
  [KO] Approbation MR requise
  [OK] Pipeline CI actif

Score : 4 / 6

Dépannage

La plupart des échecs rencontrés sur ce sujet ne sont pas des bugs mais des limites d'édition ou des droits insuffisants sur le jeton d'API. Le tableau distingue les deux cas et donne, pour chaque symptôme, la vérification qui tranche.

Symptôme	Cause probable	Correction
Audit events vides (API retourne `[]`)	Tier CE sans Premium	Mettre à niveau ou utiliser l'API MR/deployments comme alternative
Compliance framework non disponible	GitLab Ultimate requis	Utiliser des topics + includes partagés comme alternative
Streaming : pas de réception côté SIEM	URL incorrecte ou token invalide	Tester avec `curl` direct, vérifier les logs SIEM
Compliance pipeline ne se déclenche pas	Framework non attaché au projet	Vérifier Settings → General → Compliance framework
Script audit-report.sh : `jq: error`	Pas d'événements pour le filtre	Ajouter `// empty` au filtre jq pour gérer les résultats vides
`403 Forbidden` sur `/audit_events`	Token sans droits admin ou Owner	Utiliser un token Maintainer pour les events projet, Owner pour groupe
Événements manquants dans le journal	Rétention par défaut limitée	Configurer la rétention dans Admin → Settings (instance)

À retenir

L'audit et la conformité dans GitLab CI reposent sur cinq principes :

Tout est enregistré : GitLab trace les modifications de branches protégées, de variables, de permissions, de runners. Ces événements sont votre source de vérité pour répondre aux auditeurs.
L'API est votre outil d'investigation : l'interface montre un journal, l'API permet des requêtes ciblées. Automatisez les rapports avec des scripts pour ne pas dépendre d'une consultation manuelle.
Les compliance frameworks imposent des politiques : attacher un framework à un projet garantit que le compliance pipeline s'exécute, sans dépendre de la bonne volonté du développeur (GitLab Ultimate).
Le streaming transforme l'audit en surveillance : envoyer les événements vers un SIEM permet de détecter les anomalies en temps réel, pas lors de l'audit annuel.
La conformité se mesure : un score de conformité par projet, calculé automatiquement, permet d'identifier les projets à risque avant l'auditeur.

Sources

Audit events, GitLab Docs
Audit events API, GitLab Docs
Compliance frameworks, GitLab Docs
Compliance pipelines, GitLab Docs
Audit event streaming, GitLab Docs
SOC 2 compliance with GitLab, GitLab

Testez vos connaissances

Dix questions sur les audit events, les compliance frameworks et le streaming, avec un seuil de réussite à 70 %.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

5 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin

Prochaines étapes

7 attaques qui ciblent vos pipelines Comprendre les vecteurs d'attaque pour savoir quels événements surveiller en priorité.

Branches protégées et environnements Les contrôles d'accès que l'audit doit vérifier : branches, tags, environnements, freezes.

Durcir vos pipelines en 10 mesures Les 10 mesures de durcissement dont la conformité doit prouver l'application.

Supply chain CI : SBOM et attestations Les preuves cryptographiques qui complètent la traçabilité des audit events.