Commandes GitLab CI/CD de base avec exemples pratiques : guide de l'opérateur au quotidien

Introduction

Les commandes GitLab CI/CD de base avec exemples pratiques doivent vous faire passer d'un problème observé à une correction vérifiée. Commencez par identifier la version installée, la topologie de déploiement, les prérequis et le composant exact que vous inspectez.

Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui utilisent GitLab CI/CD au quotidien. Il relie les commandes de base, les exemples pratiques et une approche de type aide-mémoire à la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier chaque résultat et documenter les chemins de récupération.

Chaque procédure ci-dessous suit le même schéma :

1. Observation en lecture seule d'abord.
2. Définir le résultat attendu et le signal d'échec avant de changer quoi que ce soit.
3. Apporter la plus petite modification justifiée avec un retour en arrière connu.
4. Vérifier le résultat avec une commande concrète ou une réponse d'API.

Aucune information d'identification réelle, jeton, clé privée ou identifiant de production n'apparaît dans cet article. Remplacez tous les espaces réservés par vos propres valeurs.

Inventaire des versions et de l'environnement

Avant d'exécuter toute commande GitLab CI/CD, sachez avec quoi vous travaillez. La version détermine les options, les points de terminaison API et la syntaxe de configuration valides. La topologie indique où se trouvent les exécuteurs, comment ils se connectent et quels journaux vous pouvez atteindre.

1. Vérifier la version du serveur GitLab

Utilisez l'API de version ou la console Rails sur l'instance GitLab.

# Depuis l'hôte GitLab (lecture seule)
sudo gitlab-rake gitlab:env:info

La sortie attendue comprend :

GitLab information
Version:        16.11.0
Revision:       1234567
Directory:      /opt/gitlab/embedded/service/gitlab-rails
DB Adapter:     PostgreSQL
URL:            https://gitlab.example.com
HTTP Clone URL: https://gitlab.example.com/some-group/some-project.git
SSH Clone URL:  [email protected]:some-group/some-project.git

Signaux d'échec :

• « Permission denied » -> vous avez besoin d'un accès sudo ou administrateur GitLab.
• « rake aborted » -> l'installation GitLab peut être cassée ; vérifiez gitlab-ctl status.

2. Vérifier la version de GitLab Runner

Sur chaque hôte d'exécuteur :

gitlab-runner --version

Sortie attendue :

Version:      16.11.0
Git revision: 4b5e6f1
Git branch:   16-11-stable
GO version:   go1.21.5
Built:        2024-01-15T14:00:00Z
OS/Arch:      linux/amd64

Pourquoi les versions comptent : Le Runner 16.x utilise --registration-token pour l'enregistrement ; les versions plus récentes peuvent utiliser un jeton d'authentification depuis l'interface utilisateur. Mélanger les versions peut entraîner une « erreur interne du serveur 500 » lors de l'enregistrement des tâches.

3. Lister les exécuteurs enregistrés (nécessite un jeton administrateur)

L'API des exécuteurs montre tous les exécuteurs, leur statut, leurs étiquettes et leurs exécuteurs. Utilisez une requête GET en lecture seule avec un jeton d'accès personnel (PAT) administrateur.

curl --header "PRIVATE-TOKEN: <votre_pat_admin>" \
  "https://gitlab.example.com/api/v4/runners?per_page=50"

Une réponse d'exécuteur sain comprend :

[
  {
    "id": 42,
    "description": "docker-runner-prod",
    "active": true,
    "online": true,
    "status": "online",
    "runner_type": "group_type",
    "tag_list": ["docker", "linux", "prod"]
  }
]

Signaux d'échec :

• HTTP 401 -> PAT invalide ou portée read_api manquante.
• Tableau vide [] -> aucun exécuteur enregistré ou le jeton n'a pas la permission.

4. Enregistrer l'état actuel avant tout changement

Notez la sortie des commandes ci-dessus, y compris les horodatages. C'est votre point de retour en arrière. Par exemple :

date -u +"%Y-%m-%dT%H:%M:%SZ"
sudo gitlab-rake gitlab:env:info > gitlab_env_$(date +%F_%T).log
gitlab-runner --version > runner_version_$(date +%F_%T).log

Stockez ces journaux dans un emplacement sécurisé, pas dans le dépôt.

Chemin de configuration sécurisé

Les modifications de configuration doivent être petites, adaptées à la version et réversibles. Ne modifiez jamais plusieurs fichiers à la fois et ne mettez jamais de secrets dans gitlab-ci.yml.

1. Modifier gitlab-ci.yml en toute sécurité

La définition du pipeline est le fichier le plus fréquemment modifié. Utilisez l'API GitLab CI Lint pour le valider avant de le pousser.

# Utilisez un jeton d'accès au projet ou un PAT avec la portée 'api'
curl --header "Content-Type: application/json" \
     --header "PRIVATE-TOKEN: <votre_pat>" \
     --data '{"content": "include:\n  - local: /templates/.gitlab-ci-template.yml\n\nstages:\n  - test\n\ntest_job:\n  stage: test\n  script: echo \"Running tests\""}' \
     "https://gitlab.example.com/api/v4/ci/lint"

Réponse de succès attendue :

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "merged_yaml": "---\ninclude:\n- local: /templates/.gitlab-ci-template.yml\nstages:\n- test\ntest_job:\n  stage: test\n  script: echo 'Running tests'\n"
}

Signaux d'échec :

• "valid": false avec un tableau errors -> corrigez la syntaxe avant de valider.
• HTTP 401 -> le jeton n'a pas la portée api.

2. Configurer un exécuteur pour un projet

Si un projet a besoin d'un exécuteur dédié, enregistrez-le avec un jeton spécifique au projet (obtenu dans Paramètres > CI/CD > Runners). Utilisez l'enregistrement non interactif pour éviter les invites :

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --registration-token "<jeton_enregistrement_projet>" \
  --executor "docker" \
  --docker-image "alpine:3.19" \
  --description "project-x-runner" \
  --tag-list "docker,linux"

Vérifiez ensuite l'enregistrement :

sudo gitlab-runner verify

Sortie attendue :

Runtime platform                                    arch=amd64 os=linux pid=1234 revision=4b5e6f1 version=16.11.0
Running in system-mode.

Verifying runner... is alive                        runner=abc123

Récupération : Si l'exécuteur n'apparaît pas dans l'interface GitLab, vérifiez /etc/gitlab-runner/config.toml pour l'URL et le jeton corrects, puis exécutez gitlab-runner restart.

3. Déplacer un exécuteur entre groupes/projets en toute sécurité

Changer la portée d'un exécuteur nécessite de le désenregistrer et de le réenregistrer. Cela perturbe les tâches en cours sur cet exécuteur. Planifiez des fenêtres de maintenance en conséquence.

1. Mettez l'exécuteur en pause dans l'interface GitLab (Admin > Runners > cliquez sur l'exécuteur > Pause).
2. Attendez que les tâches actives se terminent.
3. Désenregistrez l'exécuteur de l'ancienne portée via l'API ou l'interface.
4. Réenregistrez avec le jeton de la nouvelle portée.
5. Dépausez et vérifiez.

4. Utiliser les variables CI/CD en toute sécurité

Protégez les secrets avec des variables masquées et protégées. Dans l'interface GitLab : Paramètres > CI/CD > Variables > Ajouter une variable.

• Clé : AWS_SECRET_ACCESS_KEY
• Valeur : dummy-value-123 (remplacez par le vrai secret depuis votre coffre)
• Masquer la variable : oui
• Protéger la variable : oui (uniquement sur les branches/étiquettes protégées)

Dans .gitlab-ci.yml, référencez-la sans l'afficher :

deploy:
  script:
    - aws s3 cp build s3://my-bucket --region us-east-1

N'utilisez jamais echo $AWS_SECRET_ACCESS_KEY dans les journaux. GitLab masque les variables qui correspondent à certains modèles, mais ce n'est pas infaillible.

Vérification et diagnostic

Après avoir effectué un changement, vérifiez que le système se comporte comme prévu. Utilisez des commandes en lecture seule et des requêtes API.

1. Afficher le statut du pipeline pour un commit

Utilisez l'API des pipelines pour obtenir le statut d'un pipeline pour un SHA de commit spécifique.

curl --header "PRIVATE-TOKEN: <votre_pat>" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines?sha=<commit_sha>"

Réponse attendue (simplifiée) :

[
  {
    "id": 7654,
    "status": "success",
    "ref": "main",
    "sha": "abcdef123456",
    "web_url": "https://gitlab.example.com/group/project/-/pipelines/7654"
  }
]

2. Récupérer les journaux d'une tâche échouée

Lorsqu'un pipeline échoue, identifiez la tâche échouée et extrayez les journaux via l'API :

# D'abord, listez les tâches du pipeline 7654
curl --header "PRIVATE-TOKEN: <votre_pat>" \
  "https://gitlab.example.com/api/v4/projects/123/pipelines/7654/jobs"

# Ensuite, obtenez la trace pour un ID de tâche spécifique (par exemple, 98765)
curl --header "PRIVATE-TOKEN: <votre_pat>" \
  "https://gitlab.example.com/api/v4/projects/123/jobs/98765/trace" > job_98765.log

Inspectez le journal :

grep -n "ERROR" job_98765.log

Modèles d'erreur courants :

• fatal: unable to access 'https://gitlab.example.com/...': The requested URL returned error: 403 -> vérifiez le réseau ou les informations d'identification de l'exécuteur.
• ERROR: Job failed (system failure): Error response from daemon: pull access denied -> image Docker privée ou mauvaises informations d'identification.

3. Surveiller la santé des exécuteurs

Vérifiez la concurrence des exécuteurs et les exécuteurs hors ligne depuis l'API :

curl --header "PRIVATE-TOKEN: <votre_pat_admin>" \
  "https://gitlab.example.com/api/v4/runners/all?status=online"

Comparez avec votre parc d'exécuteurs attendu. Si un exécuteur est hors ligne, vérifiez l'hôte de l'exécuteur :

sudo gitlab-runner status
sudo gitlab-runner list

4. Vérifier la configuration avec CI Lint

Lintez toujours l'ensemble du pipeline après les modifications. L'API accepte les chemins include et renvoie le YAML fusionné.

curl --header "Content-Type: application/json" \
     --header "PRIVATE-TOKEN: <votre_pat>" \
     --data '{"content": "include:\n  - project: group/templates\n    ref: main\n    file: /ci/base.yml\n\nstages:\n  - build\n\nbuild_job:\n  stage: build\n  script: echo hello"}' \
     "https://gitlab.example.com/api/v4/ci/lint"

Modes de défaillance et récupération

Même des changements prudents peuvent mal tourner. Connaissez les modes de défaillance courants et comment récupérer sans aggraver les choses.

Défaillance : échec d'authentification lors de l'enregistrement de l'exécuteur

Symptôme : ERROR: Registering runner... forbidden (check registration token)

Pourquoi : Le jeton d'enregistrement a expiré, a été révoqué, ou vous utilisez un jeton d'accès personnel au lieu d'un jeton d'enregistrement d'exécuteur.

Récupération :

1. Obtenez un nouveau jeton d'enregistrement depuis l'interface GitLab (Paramètres > CI/CD > Runners > Enregistrer un runner de groupe ou de projet).
2. Assurez-vous que le jeton est copié exactement, sans espaces de fin.
3. Si vous utilisez un jeton d'authentification (méthode plus récente), créez-le via l'API :

   curl --request POST --header "PRIVATE-TOKEN: <votre_pat>" \
     "https://gitlab.example.com/api/v4/user/runners" \
     --data "runner_type=project_type&project_id=123&description=my-runner"

La réponse contient un champ token. Utilisez ce jeton avec gitlab-runner register --token <token>.

Défaillance : pipeline bloqué en attente

Symptôme : Le pipeline affiche pending pendant longtemps, aucun exécuteur ne le prend en charge.

Causes possibles :

• Aucun exécuteur actif avec les étiquettes correspondantes.
• L'exécuteur est hors ligne ou en pause.
• Limite de concurrence de l'exécuteur atteinte.
• L'exécuteur n'est pas assigné au projet/groupe.

Étapes de diagnostic :

1. Listez les exécuteurs du projet :

   curl --header "PRIVATE-TOKEN: <votre_pat>" \
     "https://gitlab.example.com/api/v4/projects/123/runners"

Vérifiez active: true et online: true.

1. Vérifiez les étiquettes de l'exécuteur. Si la tâche a tags: [docker, linux], assurez-vous qu'un exécuteur possède les deux étiquettes.
2. Vérifiez la concurrence de l'exécuteur dans /etc/gitlab-runner/config.toml :

   concurrent = 2

Augmentez si nécessaire, puis redémarrez l'exécuteur.

1. Si aucun exécuteur n'est disponible, enregistrez-en un nouveau ou activez un exécuteur partagé.

Défaillance : secret divulgué dans les journaux de tâche

Symptôme : Une variable masquée apparaît non masquée ou un secret est accidentellement affiché.

Pourquoi : La variable ne répondait pas aux exigences de masquage (pas d'espaces, longueur >8, pas un modèle connu) ou vous l'avez explicitement imprimée.

Récupération :

1. Révoquez immédiatement le secret (par exemple, faites pivoter la clé AWS, réinitialisez le mot de passe).
2. Modifiez la tâche pour supprimer l'instruction echo.
3. Purgez les journaux de tâche si nécessaire via l'API (admin uniquement) :

   curl --request DELETE --header "PRIVATE-TOKEN: <votre_pat_admin>" \
     "https://gitlab.example.com/api/v4/projects/123/jobs/98765/artifacts"

1. Passez en revue les variables CI/CD : supprimez les secrets inutilisés, appliquez le masquage.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après tout changement CI/CD. Attribuez un responsable à chaque élément et examinez-la mensuellement.

Note sur les responsables : Pour chaque élément, une personne nommée est responsable, pas une équipe. Elle doit recevoir des alertes et examiner la vérification à la fréquence indiquée. Mettez à jour cette liste à mesure que votre environnement évolue.

Pièges courants et comment les éviter

Piège 1 : Utiliser le mauvais type de jeton

Pourquoi cela arrive : GitLab a de nombreux types de jetons : accès personnel, accès au projet, accès au groupe, enregistrement d'exécuteur, authentification d'exécuteur, jetons de déploiement. Les mélanger entraîne des échecs d'authentification.

Comment l'éviter : Vérifiez toujours la documentation de l'API pour le type de jeton requis et les portées. Utilisez des comptes de service dédiés avec le moindre privilège.

Récupération : Si vous recevez 401/403, vérifiez la portée et l'expiration du jeton. Créez un nouveau jeton avec les permissions correctes.

Piège 2 : Coder en dur des secrets dans .gitlab-ci.yml

Pourquoi cela arrive : Les développeurs veulent des solutions rapides et intègrent parfois des mots de passe directement.

Comment l'éviter : Utilisez les variables CI/CD (Paramètres > CI/CD > Variables) et ne validez jamais de secrets. Activez la détection de secrets dans le pipeline.

Récupération : Si un secret est validé, traitez-le comme compromis : faites-le pivoter immédiatement, supprimez-le de l'historique git et rechiffrez toutes les données affectées.

Piège 3 : Modifier la configuration de l'exécuteur pendant que des tâches s'exécutent

Pourquoi cela arrive : Essayer de réparer un exécuteur sans le mettre en pause d'abord.

Comment l'éviter : Mettez l'exécuteur en pause dans l'interface, attendez que les tâches se terminent, puis modifiez la configuration.

Récupération : Si un exécuteur devient incohérent, réenregistrez-le depuis zéro après l'avoir désenregistré.

Piège 4 : Ne pas épingler les versions d'image Docker

Pourquoi cela arrive : Utiliser image: latest ou des étiquettes flottantes conduit à des builds imprévisibles.

Comment l'éviter : Épinglez à une version spécifique comme image: alpine:3.19.1. Utilisez Dependabot ou des pipelines planifiés pour mettre à jour les versions épinglées.

Récupération : Revenez à l'étiquette d'image précédente connue comme bonne dans la définition du pipeline.

Conclusion

Les commandes GitLab CI/CD de base ne sont utiles que lorsqu'elles sont limitées à la version, observables et réversibles. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure d'opérations ; c'est un pari.

Comme prochaine étape, choisissez une vérification à faible risque de ce guide : vérifiez vos versions de GitLab et des exécuteurs, lintez votre configuration CI ou listez vos exécuteurs. Enregistrez l'état actuel, exécutez la vérification documentée, comparez le résultat avec le signal attendu et notez toute lacune dans votre plan de récupération.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Utilisez ce guide comme aide-mémoire quotidien et revisitez-le chaque fois que votre environnement ou la version de GitLab change.