ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Packages dbt privés via Git

Comment distribuer des packages dbt internes comme dépendances Git — épinglage de versions, options d'authentification et compromis par rapport aux packages Hub.

Planté
dbtdata engineering

Les packages internes — macros utilitaires, tests partagés, définitions de sources propres à l’entreprise — peuvent être distribués comme dépendances Git sans enregistrement sur le dbt Hub. Une progression courante est de partager via Git d’abord entre les projets d’une équipe, puis de publier sur le Hub une fois le package suffisamment stable pour un usage plus large.

Installation de base

Les utilisateurs référencent directement un dépôt Git dans packages.yml :

packages.yml
packages:
  - git: "https://github.com/my-org/dbt-internal-utils.git"
    revision: v0.3.0

L’exécution de dbt deps clone le dépôt à la révision spécifiée. Le package se comporte de manière identique à un package Hub une fois installé — même résolution de modèles, même disponibilité des macros, mêmes définitions de sources.

Épinglage de version

Épinglez sur un tag ou un SHA de commit, pas un nom de branche. C’est la règle la plus importante pour les packages Git.

# Bon — déterministe
packages:
  - git: "https://github.com/my-org/dbt-internal-utils.git"
    revision: v0.3.0


# Aussi bon — encore plus déterministe
packages:
  - git: "https://github.com/my-org/dbt-internal-utils.git"
    revision: abc1234def5678


# Dangereux — change à chaque commit
packages:
  - git: "https://github.com/my-org/dbt-internal-utils.git"
    revision: main

Pointer vers main signifie que la résolution de votre package change à chaque commit vers le dépôt en amont. Un collègue poussant un changement breaking vers le package utils partagé à 15h casse silencieusement chaque projet qui exécute dbt deps après ce point. La reproductibilité disparaît.

Les tags (utilisant le versionnage sémantique) sont la meilleure pratique. Ils sont lisibles par les humains, communiquent l’intention (est-ce un patch ou un changement breaking ?) et correspondent au fonctionnement des packages Hub. Les SHA de commit sont utiles quand vous avez besoin d’épingler à un état exact, mais ils sont plus difficiles à raisonner.

Authentification pour les dépôts privés

Pour les dépôts privés, dbt supporte trois approches d’authentification.

Authentification native par fournisseur (recommandée)

packages:
  - private: my-org/dbt-internal-utils
    provider: github
    revision: v0.3.0

Le mot-clé private avec un provider utilise l’intégration Git déjà configurée dans votre environnement — GitHub, GitLab ou Azure DevOps. C’est l’approche la plus propre parce que :

  • Aucun token intégré dans packages.yml
  • Fonctionne avec l’authentification que votre équipe utilise déjà (clés SSH, credential helpers, GitHub CLI)
  • Supporte GitHub, GitLab et Azure DevOps nativement

L’inconvénient est que cela nécessite que l’environnement d’exécution (ordinateur du développeur, runner CI, dbt Cloud) dispose de credentials Git configurés. En CI, cela signifie généralement une GitHub App ou une deploy key.

Token via variable d’environnement

packages:
  - git: "https://{{ env_var('GIT_TOKEN') }}@github.com/my-org/dbt-internal-utils.git"
    revision: v0.3.0

La fonction env_var() injecte un token au moment de la résolution. Cela fonctionne partout mais présente un inconvénient : le token apparaît dans le packages.yml résolu, ce qui signifie qu’il pourrait figurer dans les logs si dbt affiche la sortie de débogage. Utilisez un token d’accès personnel à granularité fine ou un token GitHub App avec des permissions minimales (lecture seule sur le dépôt spécifique).

SSH

packages:
  - git: "git@github.com:my-org/dbt-internal-utils.git"
    revision: v0.3.0

L’authentification SSH utilise la clé SSH configurée dans l’environnement d’exécution. C’est courant sur les ordinateurs des développeurs mais peut être délicat dans les environnements CI où vous devez gérer des deploy keys.

Compromis par rapport aux packages Hub

Les packages Git manquent de deux fonctionnalités que les packages Hub fournissent :

  1. Pas de résolution des dépendances transitives. Si votre package Git dépend de dbt-utils v1.3.0 et que le projet de l’utilisateur dépend de dbt-utils v1.2.0, vous obtenez une erreur de conflit. Les packages Hub résolvent cela automatiquement en trouvant la version la plus haute satisfaisant toutes les contraintes. Avec les packages Git, vous alignez manuellement les versions.

  2. Pas de syntaxe de plage de versions. Les packages Hub supportent [">=1.0.0", "<2.0.0"] ce qui permet à dbt de choisir la meilleure version. Les packages Git s’épinglent à une seule révision. Quand vous publiez la v0.4.0 de votre package utils interne, chaque projet consommateur doit mettre à jour manuellement son packages.yml.

Ces compromis sont gérables pour les packages internes où vous contrôlez les deux côtés. Ils deviennent douloureux à l’échelle — si 20 projets dépendent de votre package utils interne et que vous publiez une nouvelle version, 20 PRs doivent mettre à jour la révision.

Monorepo vs dépôt dédié

Pour les packages internes, vous avez le choix : placer le package dans son propre dépôt ou l’inclure dans un monorepo aux côtés d’autres projets dbt.

Dépôt dédié simplifie dbt deps :

packages:
  - git: "https://github.com/my-org/dbt-internal-utils.git"
    revision: v0.3.0

Monorepo avec sous-répertoire nécessite la clé subdirectory :

packages:
  - git: "https://github.com/my-org/analytics-monorepo.git"
    revision: v0.3.0
    subdirectory: "packages/dbt-internal-utils"

Les dépôts dédiés sont plus faciles à versionner et tagger indépendamment. Les monorepos fonctionnent quand plusieurs packages doivent être versionnés ensemble, mais le tagging indépendant devient difficile à gérer.

Un package utils interne pratique

La plupart des équipes commencent par un package « utils » qui contient des macros et des tests partagés. Une structure typique :

dbt-internal-utils/
├── dbt_project.yml
├── macros/
│   ├── generate_schema_name.sql
│   ├── cents_to_dollars.sql
│   ├── limit_data_in_dev.sql
│   └── add_audit_columns.sql
├── tests/generic/
│   ├── is_positive.sql
│   ├── date_not_in_future.sql
│   └── not_empty_string.sql
└── README.md

Ce package n’a pas de modèles — uniquement des macros et des tests génériques personnalisés. Il n’y a pas de sources à configurer et pas de modèles à nommer. Passer de la distribution Git à un package Hub nécessite d’ajouter la configuration var() pour tout ce qui est actuellement codé en dur avec des valeurs spécifiques à l’organisation.