Configurer les constructions automatisées

Note

Les constructions automatisées nécessitent un abonnement Docker Pro, Team, ou Business.

Configurer les constructions automatisées

Vous pouvez configurer des dépôts dans Docker Hub pour qu'ils construisent automatiquement une image chaque fois que vous poussez du nouveau code vers votre fournisseur source. Si vous avez des tests automatisés configurés, la nouvelle image n'est poussée que lorsque les tests réussissent.

1. Dans Docker Hub, allez à Mon Hub > Dépôts, et sélectionnez un dépôt pour voir ses détails.

2. Sélectionnez l'onglet Constructions.

3. Sélectionnez GitHub ou Bitbucket pour connecter l'endroit où le code source de l'image est stocké.

   Note

   Vous pourriez être redirigé vers la page des paramètres pour lier le service de dépôt de code. Sinon, si vous modifiez les paramètres de construction pour une construction automatisée existante, sélectionnez Configurer les constructions automatisées.

4. Sélectionnez le dépôt source pour construire les images Docker.

   Note

   Vous pourriez avoir besoin de spécifier une organisation ou un utilisateur du fournisseur de code source. Une fois que vous sélectionnez un utilisateur, les dépôts de code source apparaissent dans la liste déroulante Sélectionner le dépôt.

5. Optionnel. Activez les tests automatiques.

6. Révisez les Règles de Construction par défaut.

   Les règles de construction contrôlent ce que Docker Hub construit en images à partir du contenu du dépôt de code source, et comment les images résultantes sont étiquetées dans le dépôt Docker.

   Une règle de construction par défaut est configurée pour vous, que vous pouvez modifier ou supprimer. Cette règle par défaut configure des constructions depuis la Branche dans votre dépôt de code source appelée master ou main, et crée une image Docker étiquetée avec latest. Pour plus d'informations, voir configurer les règles de construction.

7. Optionnel. Sélectionnez l'icône plus pour ajouter et configurer plus de règles de construction.

8. Pour chaque branche ou étiquette, activez ou désactivez le bouton Construction automatique.

   Seules les branches ou étiquettes avec la construction automatique activée sont construites, testées, et ont l'image résultante poussée vers le dépôt. Les branches avec la construction automatique désactivée sont construites à des fins de test (si activé au niveau du dépôt), mais l'image Docker construite n'est pas poussée vers le dépôt.

9. Pour chaque branche ou étiquette, activez ou désactivez le bouton Cache de Construction.

   Le cache de construction peut économiser du temps si vous construisez une grande image fréquemment ou avez beaucoup de dépendances. Laissez le cache de construction désactivé pour vous assurer que toutes vos dépendances sont résolues au moment de la construction, ou si vous avez une grande couche qui est plus rapide à construire localement.

10. Sélectionnez Sauvegarder pour sauvegarder les paramètres, ou sélectionnez Sauvegarder et construire pour sauvegarder et exécuter un test initial.

    Note

    Un webhook est automatiquement ajouté à votre dépôt de code source pour notifier Docker Hub à chaque push. Seuls les pushs vers les branches qui sont listées comme source pour une ou plusieurs étiquettes, déclenchent une construction.

Configurer les règles de construction

Par défaut, quand vous configurez des constructions automatisées, une règle de construction de base est créée pour vous. Cette règle par défaut surveille les changements vers la branche master ou main dans votre dépôt de code source, et construit la branche master ou main en une image Docker étiquetée avec latest.

Dans la section Règles de Construction, entrez une ou plusieurs sources à construire.

Pour chaque source :

• Sélectionnez le Type de source pour construire soit une étiquette soit une branche. Cela indique au système de construction quoi chercher dans le dépôt de code source.

• Entrez le nom de la branche ou étiquette Source que vous voulez construire.

  La première fois que vous configurez des constructions automatisées, une règle de construction par défaut est configurée pour vous. Cet ensemble par défaut construit depuis la Branche dans votre code source appelée master, et crée une image Docker étiquetée avec latest.

  Vous pouvez aussi utiliser une regex pour sélectionner quelles branches ou étiquettes source construire. Pour en apprendre plus, voir regexes.

• Entrez l'étiquette à appliquer aux images Docker construites depuis cette source.

  Si vous avez configuré une regex pour sélectionner la source, vous pouvez référencer les groupes de capture et utiliser son résultat comme partie de l'étiquette. Pour en apprendre plus, voir regexes.

• Spécifiez l'emplacement du Dockerfile comme un chemin relatif à la racine du dépôt de code source. Si le Dockerfile est à la racine du dépôt, laissez ce chemin défini à /.

Note

Quand Docker Hub tire une branche d'un dépôt de code source, il effectue un clone superficiel - seulement la pointe de la branche spécifiée. Référez-vous à Options avancées pour autobuild et autotest pour plus d'informations.

Variables d'environnement pour les constructions

Vous pouvez définir les valeurs pour les variables d'environnement utilisées dans vos processus de construction quand vous configurez une construction automatisée. Ajoutez vos variables d'environnement de construction en sélectionnant l'icône plus à côté de la section Variables d'environnement de construction, et puis en entrant un nom de variable et la valeur.

Quand vous définissez des valeurs de variables depuis l'interface utilisateur Docker Hub, vous pouvez les utiliser par les commandes que vous définissez dans les fichiers hooks. Cependant, elles sont stockées de sorte que seuls les utilisateurs qui ont un accès admin au dépôt Docker Hub peuvent voir leurs valeurs. Cela signifie que vous pouvez les utiliser pour stocker des jetons d'accès ou d'autres informations qui devraient rester secrètes.

Note

Les variables définies sur l'écran de configuration de construction sont utilisées pendant les processus de construction seulement et ne devraient pas être confondues avec les valeurs d'environnement utilisées par votre service, par exemple pour créer des liens de service.

Options avancées de construction automatisée

Au minimum vous avez besoin d'une règle de construction composée d'une branche source, ou étiquette, et d'une étiquette Docker de destination pour configurer une construction automatisée. Vous pouvez aussi :

• Changer où la construction cherche le Dockerfile
• Définir un chemin vers les fichiers que la construction devrait utiliser (le contexte de construction)
• Configurer plusieurs étiquettes ou branches statiques depuis lesquelles construire
• Utiliser des expressions régulières (regexes) pour sélectionner dynamiquement le code source à construire et créer des étiquettes dynamiques

Toutes ces options sont disponibles depuis l'écran Configuration de construction pour chaque dépôt. Dans Docker Hub, sélectionnez Mon Hub > Dépôts, et sélectionnez le nom du dépôt que vous voulez modifier. Sélectionnez l'onglet Constructions, puis sélectionnez Configurer les constructions automatisées.

Constructions d'étiquettes et de branches

Vous pouvez configurer vos constructions automatisées pour que les pushs vers des branches ou étiquettes spécifiques déclenchent une construction.

1. Dans la section Règles de Construction, sélectionnez l'icône plus pour ajouter plus de sources à construire.

2. Sélectionnez le Type de source pour construire soit une étiquette soit une branche.

   Note

   Cela indique au système de construction quel type de source chercher dans le dépôt de code.

3. Entrez le nom de la branche ou étiquette Source que vous voulez construire.

   Note

   Vous pouvez entrer un nom, ou utiliser une regex pour correspondre à quels noms de branche ou étiquette source construire. Pour en apprendre plus, voir regexes.

4. Entrez l'étiquette à appliquer aux images Docker construites depuis cette source.

   Note

   Si vous avez configuré une regex pour sélectionner la source, vous pouvez référencer les groupes de capture et utiliser son résultat comme partie de l'étiquette. Pour en apprendre plus, voir regexes.

5. Répétez les étapes 2 à 4 pour chaque nouvelle règle de construction que vous configurez.

Définir le contexte de construction et l'emplacement du Dockerfile

Selon comment vous arrangez les fichiers dans votre dépôt de code source, les fichiers requis pour construire vos images peuvent ne pas être à la racine du dépôt. Si c'est le cas, vous pouvez spécifier un chemin où la construction cherche les fichiers.

Le contexte de construction est le chemin vers les fichiers nécessaires pour la construction, relatif à la racine du dépôt. Entrez le chemin vers ces fichiers dans le champ Contexte de construction. Entrez / pour définir le contexte de construction comme la racine du dépôt de code source.

Note

Si vous supprimez le chemin par défaut / du champ Contexte de construction et le laissez vide, le système de construction utilise le chemin vers le Dockerfile comme contexte de construction. Cependant, pour éviter la confusion il est recommandé de spécifier le chemin complet.

Vous pouvez spécifier l'emplacement du Dockerfile comme un chemin relatif au contexte de construction. Si le Dockerfile est à la racine du chemin de contexte de construction, laissez le chemin Dockerfile défini à /. Si le champ contexte de construction est vide, définissez le chemin vers le Dockerfile depuis la racine du dépôt source.

Regexes et constructions automatisées

Vous pouvez spécifier une expression régulière (regex) pour que seules les branches ou étiquettes correspondantes soient construites. Vous pouvez aussi utiliser les résultats de la regex pour créer l'étiquette Docker qui est appliquée à l'image construite.

Vous pouvez utiliser jusqu'à neuf groupes de capture d'expression régulière, ou expressions entourées de parenthèses, pour sélectionner une source à construire, et les référencer dans le champ Étiquette Docker en utilisant {\1} à {\9}.

Construire des images avec BuildKit

Les constructions automatiques utilisent le système de construction BuildKit par défaut. Si vous voulez utiliser le système de construction Docker legacy, ajoutez la variable d'environnement DOCKER_BUILDKIT=0. Référez-vous à la page BuildKit pour plus d'informations sur BuildKit.

Construction automatique pour les équipes

Quand vous créez un dépôt de construction automatisée dans votre propre compte utilisateur, vous pouvez démarrer, annuler, et réessayer des constructions, et modifier et supprimer vos propres dépôts.

Ces mêmes actions sont aussi disponibles pour les dépôts d'équipe depuis Docker Hub si vous êtes un propriétaire. Si vous êtes membre d'une équipe avec des permissions write vous pouvez démarrer, annuler, et réessayer des constructions dans les dépôts de votre équipe, mais vous ne pouvez pas modifier les paramètres de dépôt d'équipe ou supprimer les dépôts d'équipe. Si votre compte utilisateur a la permission read, ou si vous êtes membre d'une équipe avec la permission read, vous pouvez voir la configuration de construction incluant tous les paramètres de test.

Utilisateurs de service pour les constructions automatiques d'équipe

Note

Seuls les propriétaires peuvent configurer des constructions automatisées pour les équipes.

Quand vous configurez des constructions automatisées pour les équipes, vous accordez à Docker Hub l'accès à vos dépôts de code source en utilisant OAuth lié à un compte utilisateur spécifique. Cela signifie que Docker Hub a accès à tout ce à quoi le compte fournisseur source lié peut accéder.

Pour les organisations et équipes, il est recommandé de créer un compte de service dédié pour accorder l'accès au fournisseur source. Cela assure qu'aucune construction ne se casse quand les permissions d'accès d'utilisateurs individuels changent, et qu'aucun projet personnel d'utilisateur individuel n'est exposé à une organisation entière.

Ce compte de service devrait avoir accès à tous les dépôts à construire, et doit avoir un accès administratif aux dépôts de code source pour qu'il puisse gérer les clés de déploiement. Si nécessaire, vous pouvez limiter ce compte à seulement un ensemble spécifique de dépôts requis pour une construction spécifique.

Si vous construisez des dépôts avec des sous-modules privés liés (dépendances privées), vous devez aussi ajouter une variable d'environnement de remplacement SSH_PRIVATE aux constructions automatisées associées avec le compte. Pour plus d'informations, voir Dépannage

1. Créez un compte utilisateur de service sur votre fournisseur source, et générez des clés SSH pour lui.

2. Créez une équipe "build" dans votre organisation.

3. Assurez-vous que la nouvelle équipe "build" a accès à chaque dépôt et sous-module que vous devez construire.

   1. Sur GitHub ou Bitbucket, allez à la page Paramètres du dépôt.

   2. Ajoutez la nouvelle équipe "build" à la liste des utilisateurs approuvés.

      • GitHub : Ajoutez l'équipe dans Collaborateurs et Équipes.
      • Bitbucket : Ajoutez l'équipe dans Gestion d'accès.

4. Ajoutez l'utilisateur de service à l'équipe "build" sur le fournisseur source.

5. Connectez-vous à Docker Hub en tant que propriétaire, basculez vers l'organisation, et suivez les instructions pour lier au dépôt de code source en utilisant le compte de service.

   Note

   Vous pourriez avoir besoin de vous déconnecter de votre compte individuel sur le fournisseur de code source pour créer le lien vers le compte de service.

6. Optionnel. Utilisez les clés SSH que vous avez générées pour configurer toute construction avec des sous-modules privés, en utilisant le compte de service et les instructions précédentes.

Et Ensuite ?

• Personnaliser votre processus de construction avec des variables d'environnement, crochets, et plus
• Ajouter des tests automatisés
• Gérer vos constructions
• Dépannage