Intégration CI/CD de dbt-audit-helper

Exécuter dbt-audit-helper automatiquement sur chaque pull request détecte les régressions — les changements de sortie non intentionnels — avant qu’ils n’atteignent la production, sans que l’auteur de la PR ait à exécuter manuellement les macros de comparaison.

Le pattern central

La macro la mieux adaptée au CI est compare_all_columns. Elle produit un résumé par colonne montrant les comptes perfect_match, null_in_a, null_in_b, missing_from_a, missing_from_b et conflicting_values. L’envelopper dans un test qui échoue en cas de conflits :

models:
  - name: mrt__finance__revenue
    data_tests:
      - dbt_utils.expression_is_true:
          expression: "conflicting_values = 0"
          where: "1=1"

Ce test réussit quand chaque colonne du modèle dev/PR correspond exactement à la production. Toute différence déclenche un échec avec un diagnostic clair : quelles colonnes ont divergé et dans quelle mesure.

Jobs CI dbt Cloud

Dans dbt Cloud, les jobs CI déclenchés sur les pull requests compilent ref() vers le schéma PR automatiquement. Cela signifie que compare_all_columns compare naturellement le build PR avec la production sans configuration supplémentaire :

{{ audit_helper.compare_all_columns(
    a_relation=ref('mrt__finance__revenue'),
    b_relation=api.Relation.create(
      database='analytics_db',
      schema='production',
      identifier='mrt__finance__revenue'
    ),
    primary_key_columns=['revenue__id']
) }}

Ici, ref('mrt__finance__revenue') se résout vers le schéma PR tandis que api.Relation.create pointe vers la production. La comparaison se produit à chaque PR, et le job bloque le merge si des divergences sont détectées.

L’avantage clé de l’approche dbt Cloud est que la résolution de schéma est gérée automatiquement. Il n’est pas nécessaire de paramétrer le schéma cible ou de maintenir une logique spécifique à l’environnement. Le même code de macro fonctionne identiquement dans les contextes de développement, CI et production.

dbt Core avec GitHub Actions

Pour les projets dbt Core, utiliser --defer et --state pour cibler uniquement les modèles modifiés, puis exécuter les tests d’audit :

steps:
  - name: Build modified models
    run: |
      dbt build --select state:modified+ --defer --state ./prod-manifest

  - name: Run audit tests
    run: |
      dbt test --select tag:audit --store-failures

Le flag --defer indique à dbt d’utiliser les manifests de production pour tout modèle non reconstruit dans cette PR. Le flag --state pointe vers un manifest.json précédemment sauvegardé depuis l’environnement de production. Ensemble, ils garantissent que seuls les modèles modifiés sont reconstruits tandis que les dépendances non modifiées se résolvent vers leurs versions de production.

--store-failures persiste les divergences dans l’entrepôt sous forme de tables, interrogeables après l’exécution CI pour investiguer ce qui a changé et pourquoi. C’est plus utile que la sortie de logs pour un débogage complexe.

Structurer les tests d’audit

Tous les modèles n’ont pas besoin d’un test d’audit. Concentrer l’attention sur les modèles où des changements de sortie non intentionnels auraient un impact métier :

• Modèles mart consommés par des outils BI ou du reverse ETL
• Modèles avec une logique métier complexe où le risque de refactoring est le plus élevé
• Modèles alimentant des rapports financiers où même de petites différences numériques importent
• Modèles avec des consommateurs ML en aval sensibles aux dérives de distribution

Taguer les tests spécifiques à l’audit pour pouvoir les exécuter sélectivement :

models:
  - name: mrt__finance__revenue
    data_tests:
      - dbt_utils.expression_is_true:
          expression: "conflicting_values = 0"
          where: "1=1"
          tags: ["audit"]
          config:
            severity: error

La severity: error garantit que le CI échoue en cas de divergences plutôt que d’avertir simplement. Pour les modèles où de petites différences numériques sont acceptables (voir Précision en virgule flottante dans la comparaison de données), on peut utiliser severity: warn ou ajouter une logique de tolérance à l’expression.

Gérer les changements attendus

Tous les changements de sortie ne sont pas des régressions. Parfois une PR change intentionnellement la sortie du modèle — corriger un bug, ajouter une colonne, modifier un calcul. Dans ces cas, le test d’audit échouera par conception.

Options pour gérer les changements intentionnels :

1. Documenter dans la PR que les échecs d’audit sont attendus et expliquer ce qui a changé
2. Ignorer temporairement le test d’audit en supprimant le tag ou en utilisant --exclude tag:audit pour cette exécution CI spécifique
3. Mettre à jour le seuil du test si le changement introduit des différences acceptables (ex : changement d’arrondi affectant < 0,01 % des lignes)

Désactiver définitivement les tests d’audit parce qu’ils “échouent toujours” est contre-productif. Si un test détecte constamment de vrais changements, les modèles sont genuinement instables — la volatilité sous-jacente est le problème à adresser.

Investigation interactive

Quand le CI détecte des divergences, l’étape suivante est le diagnostic. --store-failures fournit des tables à interroger. Pour une investigation plus visuelle, Hex propose un template de notebook qui s’associe à audit-helper pour les workflows de validation PR — utile pour les équipes qui veulent une expérience de diagnostic plus riche que l’interrogation directe des tables d’échec stockées.

Le workflow de validation progressive s’applique ici aussi. Commencer par le résumé haut niveau de compare_all_columns depuis le CI. S’il montre des conflits, utiliser compare_which_relation_columns_differ pour affiner, puis compare_column_values pour comprendre la nature spécifique des divergences de chaque colonne.

Considérations de passage à l’échelle

audit-helper requiert une configuration manuelle par modèle. Contrairement à des outils comme Datafold qui découvrent et comparent automatiquement tous les modèles affectés dans une PR, il faut explicitement créer un test pour chaque modèle à valider. Pour les projets avec une poignée de modèles mart critiques, c’est acceptable. Pour les migrations couvrant des dizaines de modèles, la surcharge de configuration devient significative.

Pour la validation CI à l’échelle enterprise, le package dbt-audit-helper-ext d’Infinite Lambda ajoute des scripts de codegen qui auto-génèrent des macros de validation et des critères d’acceptation basés sur des seuils (100 % = réussite, 99 %+ = avertissement, en dessous de 99 % = échec). Cela réduit le coût de configuration par modèle pour les grands projets.