Utiliser Git avec des travaux Lakeflow

Les tâches de travail peuvent extraire le code source directement à partir d’un référentiel Git distant.

Les types de tâches suivants prennent en charge les dépôts Git distants :

Ordinateurs portables
scripts Python
Fichiers SQL
projets de l’outil de génération de données (dbt)

Toutes les tâches d’un projet doivent faire référence au même commit dans le dépôt distant. Lorsqu’une exécution de travail commence, Azure Databricks prend un instantané de la branche ou de la validation spécifiée afin que toutes les tâches de cette exécution utilisent la même version du code.

Lorsque vous affichez l’historique des exécutions d’une tâche qui exécute du code stocké dans un référentiel Git distant, le volet détails de l’exécution des tâches inclut les détails Git, y compris la sha de validation associée à l’exécution. Consultez Afficher l’historique des exécutions des tâches.

Note

Les tâches configurées pour utiliser un dépôt Git distant ne peuvent pas écrire dans les fichiers d’espace de travail. Ces tâches doivent écrire des données temporaires dans un stockage éphémère attaché au nœud du pilote et aux données persistantes dans un volume ou une table.

Source du référentiel Git et dossiers Git

Cette page décrit les tâches qui peuvent extraire le code source directement à partir d’un dépôt Git distant. Les espaces de travail prennent également en charge une fonctionnalité appelée dossiers Git, où un dossier de votre espace de travail est synchronisé avec un dépôt Git. Une tâche peut utiliser un dossier Git comme source. Toutefois, vous devez gérer la synchronisation avec le référentiel. L’utilisation d’un référentiel Git distant, comme décrit ici, extrait automatiquement une nouvelle source, le cas échéant, au moment de l’exécution du travail.

Azure Databricks recommande de référencer les chemins d’accès de l’espace de travail dans les dossiers Git uniquement pour une itération et un test rapides pendant le développement. Pour les travaux de préproduction et de production, configurez les tâches pour référencer un référentiel Git distant à la place.

Configurer un fournisseur Git pour un travail

L’IU des projets comporte une boîte de dialogue permettant de configurer un dépôt Git distant. Cette boîte de dialogue est accessible à partir du volet Détails du travail sous le titre Git , ou dans n’importe quelle tâche configurée pour utiliser un fournisseur Git. Pour accéder à la boîte de dialogue, cliquez sur Ajouter des paramètres Git dans le volet Détails du travail .

Dans la boîte de dialogue Git (étiquetée informations Git si elle est ouverte pendant la configuration de la tâche), entrez les détails suivants :

l’URL du référentiel Git.
Sélectionnez votre fournisseur Git dans la liste déroulante.
Dans le champ Référence Git, saisissez l’identifiant d’une branche, d’une balise ou d’un commit correspondant à la version du code source que vous souhaitez exécuter.
Sélectionnez la branche, la balise ou la validation dans la liste déroulante.

Vous ne devez spécifier qu’un des éléments suivants :

branche : nom de la branche, par exemple main.
balise : nom de la balise, par exemple release-1.0.0.
commit : code de hachage d’un commit spécifique, par exemple e0056d01.

Note

La boîte de dialogue peut vous demander ce qui suit : Il manque des identifiants Git pour ce compte. Veuillez ajouter ces identifiants. Vous devez configurer un dépôt Git distant avant de l’utiliser comme référence. Consultez Configurer l’intégration Git pour les dossiers Git.

Exécuter un travail Git en tant que rôle

Important

L’exécution d’un travail en tant que rôle nécessite un contrôle d’accès en fonction du rôle (RBAC), qui est en préversion publique.

Si votre espace de travail utilise RBAC, vous pouvez définir l’identité Exécuter en tant que d’un job comme un groupe (rôle). La tâche clone ensuite son référentiel Git à l’aide des identifiants Git du rôle ; un administrateur doit donc d’abord configurer ces identifiants, sinon la tâche ne pourra pas cloner le dépôt. Pour définir « Run as » d’une tâche sur un groupe, consultez Définir « Run as » sur un groupe.

Pour corriger une tâche qui échoue en raison d’un problème dans le code, utilisez l’une des méthodes de création dans le référentiel et sur la branche de la tâche. Assumez le rôle pour reproduire et résoudre le problème sur les données du rôle, validez le correctif, puis réexécutez le travail.

Extraction rare pour les grands dépôts

Pour les grands référentiels, vous pouvez utiliser l’extraction éparse pour importer uniquement des répertoires spécifiques plutôt que le référentiel complet. L’extraction rare réduit le temps d’extraction ainsi que l’utilisation des ressources pour chaque exécution de travail.

Toutefois, une configuration incorrecte peut entraîner une fragmentation du cache, ce qui dégrade les temps d’exécution dans l’ensemble de votre espace de travail. Cette section décrit les compromis et les problèmes qui peuvent survenir lors de l'utilisation d'un checkout partiel.

Comment Azure Databricks met en cache les extractions du référentiel

Azure Databricks met en cache chaque extraction Git en fonction de quatre valeurs :

Workspace
URL du dépôt
Hachage exact du commit
Empreinte du modèle d’extraction rare (l’ensemble exact des chemins de dossiers)

Toute exécution de travail qui correspond aux quatre critères réutilise une entrée de cache, qui reste valide pendant une semaine maximum. Par exemple, si vous avez 3 travaux différents et qu’ils ont tous les mêmes critères, ils utilisent le même cache dans le référentiel jusqu’à ce qu’il y ait une nouvelle validation (ou après 1 semaine).

Chaque modèle de checkout éparse unique crée une empreinte distincte, et donc une entrée de cache distincte. Si 20 utilisateurs ajoutent chacun un dossier personnalisé à leur modèle, le système crée 20 clés de cache distinctes et importe l’arborescence de dossiers partagés 20 fois, multipliant la charge sur votre espace de travail. En revanche, créer un seul modèle d’extraction rare qui inclut les 20 dossiers (par exemple, un dossier parent commun) permet d’utiliser un unique cache de manière plus efficace et d’améliorer les performances des travaux. Le compromis est d’obtenir un plus grand nombre de fichiers dans l’extraction.

Décider s’il faut utiliser l’extraction rare

Activez uniquement l’extraction rare si votre cas d’usage répond aux deux critères suivants :

Taille : votre référentiel est volumineux (par exemple, il dépasse 2 500 fichiers).
Ciblage stable : la branche cible est mise à jour rarement (par exemple, environ une validation par heure ou moins). Évitez les branches qui changent rapidement en raison de flux de travail CI/CD automatisés.

Si vous utilisez l’extraction éparse, votre organisation doit également adopter une ou les deux stratégies de modèle suivantes :

Normalisation : Utilisez trois modèles d’extraction partagés ou moins dans l’organisation pour optimiser les accès au cache.
Micro-ciblage : modèles de structure afin que chacun cible un petit nombre de fichiers. Pour des performances optimales, ciblez moins de 200 fichiers.

Ceux-ci peuvent vous aider à réduire votre taux d’importation.

Calculer votre taux d’importation

Avant d’activer l’extraction rare, estimez votre taux d’importation projeté de fichiers par heure. Les limites s’appliquent au niveau de l’espace de travail pour tous les travaux et utilisateurs.

Fichiers par heure = Exécutions de travaux par heure × taux d’échec d’accès au cache × nombre de fichiers importés par échec

Facteur	Qu’est-ce qui le pilote ?
Exécutions de travaux par heure	Fréquence du déclencheur pour tous les utilisateurs
Taux d’échec d’accès au cache	Fréquence des commits sur la branche cible et nombre de modèles d’extraction rare uniques
Nombre de fichiers importés par échec	Taille totale du dépôt ou taille du sous-ensemble utilisé par l’extraction rare

Exemple : 180 exécutions/heure × 10 % taux de ratés × 6 000 fichiers/raté = 108 000 fichiers/heure

Comparez votre résultat par rapport à ces seuils :

Fichiers importés par heure	Impact attendu de l’espace de travail
Inférieur à 150 000	Opération normale
150,000 – 300,000	Performances détériorées. Certains travaux peuvent rencontrer des retards ou des échecs.
Au-dessus de 300 000	Les travaux ne sont pas terminés de manière fiable.

Meilleures pratiques

Normaliser les modèles

À faire : publier trois modèles d’extraction rare approuvés ou moins par dépôt. Les modèles partagés consolident la charge et optimisent les accès au cache.
N’autorisez pas les modèles personnalisés par équipe. Même un dossier supplémentaire crée une entrée de cache et déclenche une réimportation complète.

Gérer l’évolution des commits

À faire : orienter les travaux vers une branche de mise en production stable. Regrouper les fusions par lots dans des créneaux de mise en production planifiés afin que plusieurs exécutions partagent le même commit mis en cache.
À éviter : utiliser l’extraction rare avec des branches fréquemment mises à jour comme master ou main. Étant donné que le cache est basé sur le hachage de validation exact, chaque nouvelle validation invalide le cache et provoque une réimportation complète pour chaque exécution de travail.

Gérer la charge

À faire : supprimer les fichiers binaires volumineux, les artefacts générés et les fichiers de données du contrôle de code source afin de réduire systématiquement la taille du dépôt.
À éviter : laisser des travaux redondants s’exécuter à une fréquence élevée. Réduisez la fréquence de déclenchement pour les tâches qui ne nécessitent pas d'exécution continue, échelonnez les plannings ou consolidez les tâches qui partagent le même dépôt.

Gérer l’évolution des commits avec une branche de mise en production

Lorsque les tâches ciblent une branche évoluant rapidement comme master ou main, le hachage de validation change fréquemment, ce qui provoque des ratés de cache sur presque toutes les exécutions. L’utilisation d’une branche de mise en production dédiée qui est mise à jour selon une planification fixe améliore les taux d’accès au cache.

En orientant tous les travaux vers une branche de mise en production mise à jour chaque heure, toutes les exécutions effectuées pendant cette heure correspondent au même hachage de commit et partagent donc la même entrée de cache.

Pour configurer une release branch :

Créez une branche de longue vie (par exemple, release-candidate) dans votre dépôt Git.
Automatisez la mise à jour de cette branche pour qu'elle soit en concordance avec master selon un calendrier fixe, comme le début de chaque heure.
Configurez vos travaux soutenus par Git pour qu’ils utilisent release-candidate comme référence Git cible.

Passez en revue ces compromis avant d’implémenter :

Point à considérer	Description
Retard de commit	Les travaux s’exécutent avec un code pouvant avoir jusqu’à une heure de retard par rapport à `master`. Cela est acceptable pour la plupart des charges de travail par lots, mais peut ne pas convenir aux travaux nécessitant le dernier commit.
Fenêtre d’échec	Si le travail de création de version échoue, la branche n’est pas mise à jour pendant cette heure et les travaux continuent de s’exécuter sur le commit précédent. Databricks recommande de configurer des alertes sur le travail de création de version.

Exemple : automatiser avec GitHub Actions

Le flux de travail GitHub Actions suivant automatise la création d’une branche de mise en production toutes les heures.

Étape 1 : Commiter un .github/workflows/cut-release-branch.yml fichier dans votre référentiel :

name: Cut Hourly Release Candidate

on:
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-branch:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout main branch
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: Update release-candidate branch
        run: |
          git push origin HEAD:release-candidate --force

Step 2 : déclenchez manuellement l’action de GitHub pour vérifier que la branche release-candidate est créée.

Étape 3 : Mettez à jour vos travaux existants à utiliser release-candidate comme référence Git cible.

Activer l’extraction rare via l’API Travaux

Pour activer l’extraction éparse, incluez un bloc sparse_checkout à l’intérieur de git_source lors de la création ou de la mise à jour d’une tâche :

{
  "git_source": {
    "git_url": "https://github.com/example/my-repo",
    "git_provider": "gitHub",
    "git_branch": "release-candidate",
    "sparse_checkout": {
      "patterns": ["src/models", "src/utils"]
    }
  }
}

Chaque chaîne dans patterns est un chemin d’accès de répertoire par rapport à la racine du référentiel. Tous les fichiers de chaque dossier spécifié sont inclus dans l’extraction.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-22