Intégration CI

gapline est conçu pour être intégré dans un pipeline : un binaire statique unique, une sortie JSON, des codes de retour stables. Ce guide montre comment le brancher dans les plateformes CI courantes et dans un hook pre-commit local.

Installer gapline en CI

Le script d’installation officiel fonctionne dans n’importe quel runner Linux. Épinglez une version pour rendre les upgrades explicites :

curl -fsSL https://gapline.dev/install.sh | sh -s -- --version 1.0.1
echo "$HOME/.local/bin" >> "$GITHUB_PATH"   # ou l'équivalent pour votre CI

Si votre runner cache des binaires entre builds, restaurez ~/.local/bin/gapline avant de relancer l’installation.

Recettes par plateforme

name: Validate GTFS

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install gapline
        run: |
          curl -fsSL https://gapline.dev/install.sh | sh -s -- --version 1.0.1
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Validate feed
        run: gapline validate -f data/gtfs.zip --format json -o report.json

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: gtfs-report
          path: report.json

validate sort non nul sur les anomalies ERROR, ce qui fait échouer le job automatiquement. if: always() garantit l’upload du rapport même sur un build rouge.

validate_gtfs:
  image: ubuntu:24.04
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -fsSL https://gapline.dev/install.sh | sh -s -- --version 1.0.1
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - gapline validate -f data/gtfs.zip --format json -o report.json
  artifacts:
    when: always
    paths:
      - report.json
    expire_in: 30 days

#!/usr/bin/env bash
set -euo pipefail

if ! command -v gapline >/dev/null; then
  curl -fsSL https://gapline.dev/install.sh | sh -s -- --version 1.0.1
  export PATH="$HOME/.local/bin:$PATH"
fi

gapline validate -f data/gtfs.zip --format json -o report.json

Fonctionne dans Jenkins, Buildkite, CircleCI, Woodpecker, et tout ce qui sait exécuter un script shell.

Analyser le rapport JSON

Avec jq, transformez le rapport en résumé humain, métrique dashboard, ou commentaire PR.

# Compteurs principaux.
jq '.summary' report.json

# Règles les plus fréquentes.
jq -r '.errors | group_by(.rule_id)
       | map({rule: .[0].rule_id, count: length})
       | sort_by(-.count) | .[:10] | .[]
       | "\(.count)\t\(.rule)"' report.json

Poster un commentaire sur une PR GitHub

summary=$(jq -r '"- \(.summary.error_count) erreurs\n- \(.summary.warning_count) avertissements\n- \(.summary.info_count) infos"' report.json)
gh pr comment "$PR_NUMBER" --body "### Validation GTFS\n$summary"

Contrôler la sévérité

Le défaut — échec sur toute ERROR — suffit dans la plupart des cas. Resserrez la porte dans les contextes stricts :

# Échec aussi sur les avertissements.
gapline validate -f data/gtfs.zip --min-severity warning --format json -o report.json

Voir concepts / sévérités pour la politique.

Hook pre-commit

Un hook local empêche un flux manifestement cassé d’atterrir dans le repo :

#!/usr/bin/env bash
set -e

if git diff --cached --name-only | grep -q '^data/gtfs'; then
  echo "Validation gapline sur le flux en staging…"
  gapline validate -f data/gtfs.zip --min-severity error
fi

Rendre exécutable :

chmod +x .git/hooks/pre-commit

Pour une version d’équipe livrée avec le repo, utilisez pre-commit, lefthook ou husky.

Mettre le flux en cache

Si le flux est gros ou téléchargé d’une source lente, mettez-le en cache entre runs, clé indexée sur son hash :

- name: Restore feed cache
  uses: actions/cache@v4
  with:
    path: data/gtfs.zip
    key: gtfs-${{ hashFiles('data/gtfs.zip.sha256') }}

Commitez le fichier de hash ; mettez-le à jour quand vous rafraîchissez le flux. Le téléchargement n’a lieu que si le hash change.

Voir aussi

gapline validate — toutes les options, tous les codes de retour.
Formats de sortie — le schéma JSON que vous allez analyser.
Concepts / Codes de retour — brancher sur succès vs config vs I/O.
Guides / Valider des flux — le workflow manuel derrière la version CI.