Créer et gérer des déclencheurs de compilation

Un déclencheur Cloud Build lance automatiquement une compilation chaque fois que vous apportez des modifications à votre code source. Vous pouvez configurer le déclencheur afin de compiler votre code pour toute modification apportée au dépôt source ou bien uniquement pour les modifications correspondant à certains critères.

Cette page explique comment se connecter aux dépôts sources, tels que GitHub et Bitbucket, et comment créer des déclencheurs de compilation afin de compiler le code hébergé dans ces dépôts.

Avant de commencer

  • Activez l'API Cloud Build

    Activer l'API

  • Vous devez disposer du rôle Éditeur Cloud Build (roles/cloudbuild.builds.editor) dans votre projet pour créer des déclencheurs.
  • Vous avez besoin du code source dans Cloud Source Repositories, GitHub ou Bitbucket.
  • Vous aurez besoin d'un fichier Dockerfile ou d'un fichier de configuration de compilation Cloud Build.

Se connecter aux dépôts sources

Pour commencer, vous devez connecter Cloud Build à votre dépôt source avant de pouvoir compiler le code hébergé dans ce dépôt. Vos dépôts hébergés dans Cloud Source Repositories sont connectés à Cloud Build par défaut. Vous pouvez créer directement des déclencheurs pour vos dépôts dans Cloud Source Repositories sans avoir besoin de les connecter manuellement.

Si vous connectez un dépôt externe, tel qu'un dépôt hébergé sur GitHub ou Bitbucket, vous aurez besoin d'autorisations d'administrateur sur le dépôt pour connecter initialement votre dépôt à Cloud Build. Les autorisations d'administrateur ne sont pas requises pour créer des déclencheurs dans un dépôt déjà connecté à Cloud Build.

Pour vous connecter à GitHub ou à Bitbucket, procédez comme suit:

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs

  2. Sélectionnez votre projet et cliquez sur Ouvrir.

  3. Sélectionnez la région dans laquelle vous souhaitez créer votre déclencheur dans le menu déroulant Région.

  4. Cliquez sur Connecter un dépôt.

  5. Sélectionnez le dépôt hébergeant votre code source.

    Si vous sélectionnez comme dépôt source GitHub (dupliqué) ou Bitbucket (dupliqué), Cloud Build met en miroir votre dépôt dans Cloud Source Repositories et utilise le dépôt dupliqué pour toutes ses opérations.

  6. Cliquez sur Continuer.

  7. Authentifiez-vous auprès de votre dépôt source à l'aide de votre nom d'utilisateur et de votre mot de passe.

  8. Dans la liste des dépôts disponibles, sélectionnez le dépôt de votre choix, puis cliquez sur Connecter.

    Pour les dépôts externes, tels que GitHub et Bitbucket, vous devez disposer d'autorisations de niveau propriétaire pour le projet Google Cloud avec lequel vous travaillez.

  9. Cliquez sur Créer un déclencheur pour poursuivre vers la création d'un déclencheur de compilation afin d'automatiser la compilation du code source du dépôt, ou bien sur OK.

Créer un déclencheur de compilation

Console

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs

  2. Sélectionnez votre projet dans le menu déroulant du sélecteur de projet, en haut de la page.

  3. Cliquez sur Ouvrir.

  4. Cliquez sur Créer un déclencheur.

  5. Entrez les paramètres de déclencheur suivants :

    • Nom : saisissez le nom de votre déclencheur.

    • Région: sélectionnez la région du déclencheur.

      Si le fichier de configuration de compilation associé à votre déclencheur spécifie un pool privé, la région que vous sélectionnez pour votre déclencheur doit correspondre à celle du pool privé.

      Si vous sélectionnez global comme région, Cloud Build utilise la région spécifiée dans le fichier de configuration de compilation pour exécuter la compilation. Il peut s'agir de la région du pool privé (si vous spécifiez un pool privé dans votre fichier de configuration de compilation) ou du pool global par défaut si vous ne spécifiez pas de pool privé.

    • Description (facultative) : saisissez une description du déclencheur.

    • Événement : sélectionnez l'événement lié au dépôt qui appelle votre déclencheur.

      • Déployer sur une branche : configurez votre déclencheur pour lancer une compilation sur les commits réalisés dans une branche spécifique.

      • Transférer le nouveau tag : configurez votre déclencheur pour lancer une compilation sur des commits contenant un tag particulier.

      • Demande d'extraction: configurez votre déclencheur pour démarrer une compilation sur les commits d'une demande d'extraction d'extraction.

    • Source: sélectionnez la source 1re génération ou 2e génération. Vous ne pouvez connecter des dépôts à partir de GitHub et de GitHub Enterprise que lorsque vous sélectionnez 2e génération comme source. Pour en savoir plus, consultez la section Dépôts Cloud Build.

      • Dépôt : sélectionnez le dépôt de votre choix dans la liste des dépôts disponibles. Pour connecter un nouveau dépôt, consultez la section Connexion aux dépôts sources.
      • Branche ou tag : spécifiez une expression régulière à laquelle faire correspondre la valeur de la branche ou du tag. Les barres obliques (/) ne peuvent pas être utilisées dans les tags. Pour en savoir plus sur la syntaxe des expressions régulières acceptable, consultez la page Syntaxe RE2.

        Lorsque la compilation s'exécute, Cloud Build copie le contenu de votre dépôt dans /workspace, le répertoire de travail par défaut pour Cloud Build. Pour en savoir plus sur les répertoires de travail, consultez la page Présentation de la configuration des compilations.

        Pour n'autoriser que les compilations provenant de sources spécifiques, définissez une règle d'administration pour les intégrations autorisées (constraints/cloudbuild.allowedIntegrations) afin de refuser les interactions avec la source définie dans votre déclencheur. La règle d'administration remplace le déclencheur et votre compilation n'est pas exécutée. Pour en savoir plus, consultez la section Compilations de porte sur les règles d'administration pour votre projet.

    • Fichiers inclus (facultatif) : les modifications affectant au moins l'un de ces fichiers déclencheront une compilation. Vous pouvez utiliser des chaînes glob pour spécifier plusieurs fichiers avec des caractères génériques. Les caractères génériques acceptables incluent les caractères pris en charge par Go Match, ** et alternation.

    • Fichiers ignorés (facultatif) : les modifications affectant uniquement des fichiers ignorés ne déclencheront pas de compilation. Vous pouvez utiliser des chaînes glob pour spécifier plusieurs fichiers avec des caractères génériques. Les caractères génériques acceptables incluent les caractères pris en charge par Go Match, ** et alternation.

      Si vous spécifiez un fichier à la fois dans Fichiers inclus et dans Fichiers ignorés, les modifications apportées à ce fichier ne déclenchent pas de compilation. Supposons que vous spécifiez **/README.md dans Fichiers ignorés pour ignorer README.md dans n'importe quel répertoire, et spécifiez src/* dans Fichiers inclus pour déclencher une compilation sur les modifications des fichiers du dossier src/. Si vous apportez une modification à src/README.md, Cloud Build ne déclenche pas de compilation. Chaque fois que vous envoyez une modification dans votre code source, Cloud Build recherche des fichiers inclus et ignorés dans vos fichiers modifiés pour déterminer si une compilation doit être appelée :

      • Si vous exécutez une modification dans le dépôt sur une branche existante, Cloud Build examine les fichiers modifiés entre le commit que vous venez d'exécuter et le commit vers lequel la branche était précédemment dirigée.
      • Si votre dépôt est un dépôt Cloud Source Repositories et que vous déployez une modification dans une branche nouvellement créée, Cloud Build traite tous les fichiers du dépôt comme des fichiers modifiés.
      • Si vous supprimez une branche, Cloud Build ne déclenche pas de compilation.
    • Configuration: sélectionnez le fichier de configuration de compilation situé dans votre dépôt distant ou créez un fichier de configuration de compilation intégré à utiliser pour votre compilation.

      • Type: sélectionnez le type de configuration à utiliser pour votre compilation.
        • Fichier de configuration Cloud Build (yaml or json) : utilisez un fichier de configuration de compilation pour votre configuration.
        • Dockerfile: utilisez un fichier Dockerfile pour votre configuration.
        • Buildpacks: utilisez des packs de création pour votre configuration.
      • Emplacement: spécifiez l'emplacement de votre configuration.

        • Dépôt: si votre fichier de configuration se trouve dans votre dépôt distant, indiquez l'emplacement de votre fichier de configuration de compilation, le répertoire Dockerfile ou le répertoire des packs de compilation. Si votre type de configuration de compilation est un fichier Dockerfile ou un pack de création, vous devez attribuer un nom à l'image obtenue et, éventuellement, un délai avant expiration pour la compilation. Une fois le nom de l'image Dockerfile ou du pack de création fourni, vous obtenez un aperçu de la commande docker build ou pack que votre compilation va exécuter.
        • Variables d'environnement de pack de création (facultatif): si vous avez sélectionné buildpacks comme type de configuration, cliquez sur Ajouter une variable d'environnement de pack pour spécifier les variables d'environnement et valeurs de votre pack de création. Pour en savoir plus sur les variables d'environnement du pack de création, consultez la section Variables d'environnement.
        • Intégré: si vous avez sélectionné Fichier de configuration Cloud Build (yaml ou json) comme option de configuration, vous pouvez spécifier votre configuration de compilation de manière intégrée. Cliquez sur Open Editor (Ouvrir l'éditeur) pour écrire votre fichier de configuration de compilation dans la console Google Cloud en utilisant la syntaxe YAML ou JSON. Cliquez sur OK pour enregistrer la configuration de compilation.

    • Utiliser un pool privé: ce champ apparaît si vous avez sélectionné Dockerfile comme option de configuration. Cochez cette case si vous exécutez votre compilation dans un pool privé.

    • Pool privé: si vous avez sélectionné Utiliser un pool privé, spécifiez le nom de ressource du pool privé au format projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

    • Variables de substitution (facultatives) : si vous avez choisi un fichier de configuration Cloud Build pour configurer la compilation, ce champ vous permet de définir des variables de substitution spécifiques à ce déclencheur. Par exemple, supposons que vous créez plusieurs déclencheurs, chacun visant à déployer votre application dans un environnement spécifique. Vous pouvez indiquer dans votre fichier de configuration que votre application est déployée dans un environnement, puis utiliser ce champ pour définir des variables de substitution spécifiant vers quel environnement ce déclencheur doit effectuer le déploiement. Pour en savoir plus sur la manière de spécifier des valeurs de substitution dans les fichiers de configuration de compilation, consultez la page Remplacer les valeurs des variables.

    • Approval (Approbation) (facultatif): cochez la case pour exiger une approbation avant l'exécution de votre compilation.

    • Compte de service: sélectionnez le compte de service à utiliser lors de l'appel de votre déclencheur. Si vous ne sélectionnez pas de compte de service, le compte de service Cloud Build par défaut est utilisé.

  6. Cliquez sur Créer pour enregistrer le déclencheur de compilation.

gcloud

Si votre code source se trouve dans Cloud Source Repositories, procédez comme suit pour créer un déclencheur :

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

Où :

  • REPO_NAME est le nom du dépôt.
  • BRANCH_PATTERN est le nom de la branche de votre dépôt sur lequel appeler la compilation.
  • TAG_PATTERN est le nom du tag de votre dépôt sur lequel appeler la compilation.
  • BUILD_CONFIG_FILE correspond au chemin d'accès à votre fichier de configuration de compilation.

  • SERVICE_ACCOUNT correspond à l'adresse e-mail associée à votre compte de service. Si vous n'incluez pas cette option, le compte de service Cloud Build par défaut est utilisé.

  • [Facultatif] --require-approval est l'option à inclure pour configurer votre déclencheur de sorte qu'il nécessite une approbation.

Pour obtenir la liste complète des options, consultez la section de la documentation de référence de gcloud consacrée à la création de déclencheurs pour Cloud Source Repositories.

Si votre code source se trouve dans GitHub, procédez comme suit pour créer un déclencheur :

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

Où :

  • REGION est la région de votre déclencheur.
  • REPO_NAME est le nom du dépôt.
  • REPO_OWNER est le nom d'utilisateur du propriétaire du dépôt.
  • BRANCH_PATTERN est le nom de la branche de votre dépôt sur lequel appeler la compilation.
  • TAG_PATTERN est le nom du tag de votre dépôt sur lequel appeler la compilation.
  • BUILD_CONFIG_FILE correspond au chemin d'accès à votre fichier de configuration de compilation.
  • SERVICE_ACCOUNT correspond à l'adresse e-mail associée à votre compte de service. Si vous n'incluez pas cette option, le compte de service Cloud Build par défaut est utilisé.
  • [Facultatif] --require-approval est l'option à inclure pour configurer votre déclencheur de sorte qu'il nécessite une approbation.
  • [Facultatif] --include-logs-with-status est une option que vous pouvez spécifier pour afficher les journaux de compilation de vos dépôts. Cet indicateur est compatible avec les builds provenant des dépôts GitHub et GitHub Enterprise.

Pour obtenir la liste complète des options, consultez la section de la documentation de référence de gcloud consacrée à la création de déclencheurs pour GitHub.

Une fois que vous avez exécuté la commande gcloud pour créer un déclencheur associé à Cloud Source Repositories ou à GitHub, vous devriez voir un résultat semblable à ce qui suit :

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

Tester un déclencheur de compilation

Pour tester manuellement un déclencheur de compilation, procédez comme suit :

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs

  2. Identifiez votre déclencheur dans la liste, puis cliquez sur Exécuter le déclencheur.

Ignorer un déclencheur de compilation

Dans certains cas, vous souhaiterez peut-être modifier votre code source sans pour autant déclencher de compilation. Par exemple, il n'est pas souhaitable de déclencher une compilation lorsque vous mettez à jour une documentation ou des fichiers de configuration.

Dans de tels scénarios, vous pouvez inclure [skip ci] ou [ci skip] dans le message de commit afin d'empêcher le déclenchement d'une compilation.

Si vous souhaitez exécuter une compilation de ce commit ultérieurement, utilisez le bouton Exécuter le déclencheur de la page Déclencheurs.

Inclure l'historique du dépôt dans une compilation

Pour compiler la source dans un dépôt Git, Cloud Build exécute un clone superficiel du dépôt. Cela signifie que seul le commit ayant déclenché la compilation est extrait dans l'espace de travail à compiler. Cloud Build ne consulte aucun autre historique ni branche. Ceci est effectué par souci d'efficacité, afin que les compilations n'aient pas à attendre pour récupérer l'intégralité du dépôt et de l'historique uniquement pour compiler un seul commit.

Si vous souhaitez inclure plus d'historique de dépôt dans la compilation, ajoutez une étape de compilation à votre fichier de configuration de compilation afin de "remplir" le clone. Exemple :

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

Pour en savoir plus sur git fetch, consultez la documentation de référence de git. Pour obtenir des instructions sur l'écriture d'un fichier de configuration de compilation, consultez la section Présentation de la configuration de compilation.

Envoyer à nouveau une compilation pour approbation

Si votre build a été refusé, vous pouvez le renvoyer pour approbation en suivant ces étapes dans la console Google Cloud:

  1. Ouvrez la page Historique Cloud Build dans la console Google Cloud.

    Ouvrir la page Historique de Cloud Build

  2. Cliquez sur l'ID de la compilation que vous souhaitez renvoyer pour approbation.

  3. Cliquez sur Recompiler en haut de la page pour renvoyer votre compilation pour approbation.

Votre compilation démarre lorsqu'un utilisateur disposant des autorisations l'approuve. Pour en savoir plus sur les approbations Cloud Build, consultez la section Compilations de porte après approbation.

Mettre à jour un déclencheur de compilation

Console

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs de compilation

  2. Sélectionnez votre projet dans le menu déroulant du sélecteur de projet, en haut de la page.

  3. Cliquez sur Ouvrir.

  4. Recherchez la ligne du déclencheur que vous souhaitez mettre à jour.

  5. Cliquez sur le menu (trois points alignés verticalement) situé à l'extrémité droite de cette ligne.

  6. Sélectionnez Modifier.

gcloud

Pour mettre à jour un déclencheur:

  1. Exportez le déclencheur que vous souhaitez mettre à jour:

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    Où :

    • TRIGGER_NAME correspond au nom de votre déclencheur.
    • EXPORT_PATH est le chemin d'accès au fichier vers lequel vous souhaitez exporter le déclencheur. Par exemple, vous pouvez spécifier votre chemin de fichier sous la forme examples/trigger.yaml. Veuillez noter que le nom de fichier de votre déclencheur doit avoir l'extension .yaml.
  2. Ouvrez le fichier contenant votre déclencheur exporté.

    Votre fichier se présentera comme suit :

     createTime: '2022-05-26T21:56:11.830784153Z'
     filename: cloudbuild.yaml
     github:
       name: cloud-build-example
       owner: main
       push:
         branch: master
     id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
     # remove field name and value to not show build logs
     includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
     name: trigger-001
    
  3. Modifiez manuellement le fichier pour mettre à jour votre déclencheur.

    Pour afficher les champs que vous pouvez ajouter ou supprimer dans votre déclencheur, consultez la ressource du déclencheur.

  4. Enregistrez votre fichier.

  5. Importez votre déclencheur :

     gcloud builds triggers import --source=IMPORT_PATH
    

    Où :

    • IMPORT_PATH est le chemin d'accès au fichier du déclencheur que vous souhaitez importer.

Votre déclencheur de compilation a été mis à jour.

Désactiver un déclencheur de compilation

Console

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs de compilation

  2. Sélectionnez votre projet dans le menu déroulant du sélecteur de projet, en haut de la page.

  3. Cliquez sur Ouvrir.

  4. Localisez la ligne correspondant au déclencheur que vous souhaitez désactiver.

  5. Cliquez sur le menu (trois points alignés verticalement) situé à l'extrémité droite de cette ligne.

  6. Sélectionnez Désactiver.

gcloud

Pour désactiver un déclencheur, procédez comme suit :

  1. Exportez le déclencheur que vous souhaitez désactiver :

     gcloud builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
    

    Où :

    • TRIGGER_NAME correspond au nom de votre déclencheur.
    • EXPORT_PATH est le chemin d'accès au fichier vers lequel vous souhaitez exporter le déclencheur. Par exemple, vous pouvez spécifier votre chemin de fichier sous la forme examples/trigger.yaml. Veuillez noter que le nom de fichier de votre déclencheur doit avoir l'extension .yaml.
  2. Ouvrez le fichier contenant votre déclencheur exporté.

    Votre fichier se présentera comme suit :

     createTime: '2020-02-21T20:02:50.215599013Z'
     description: Push to any branch
     filename: cloudbuild.yaml
     github:
       name: example-repo-name
       owner: example-owner
       push:
         branch: .*
     id: example-id
     name: Push-to-any-branch
     tags:
     - github-default-push-trigger
    
  3. Ajoutez le champ disabled à la fin de votre fichier et définissez la valeur sur True.

     disabled: True
    
  4. Enregistrez votre fichier.

  5. Importez votre déclencheur :

     gcloud builds triggers import --source=IMPORT_PATH
    

    Où :

    • IMPORT_PATH est le chemin d'accès au fichier du déclencheur que vous souhaitez importer.

Le déclencheur de compilation est maintenant désactivé.

La désactivation d'un déclencheur ne supprime pas le déclencheur. Pour supprimer un déclencheur, consultez la section Supprimer un déclencheur de compilation. Vous pouvez réactiver un déclencheur en définissant son état sur Activé.

Supprimer un déclencheur de compilation

Console

  1. Ouvrez la page Déclencheurs dans la console Google Cloud.

    Ouvrir la page Déclencheurs de compilation

  2. Sélectionnez votre projet dans le menu déroulant du sélecteur de projet, en haut de la page.

  3. Cliquez sur Ouvrir.

  4. Localisez la ligne correspondant au déclencheur que vous souhaitez supprimer.

  5. Cliquez sur le menu (trois points alignés verticalement) situé à l'extrémité droite de cette ligne.

  6. Sélectionnez Supprimer.

gcloud

Pour supprimer un déclencheur, exécutez la commande suivante :

  gcloud builds triggers delete TRIGGER_NAME

Où :

  • TRIGGER_NAME correspond au nom de votre déclencheur.

Pour obtenir la liste complète des options, consultez la section de la documentation de référence de gcloud consacrée à la suppression de déclencheurs.

Implications de sécurité des déclencheurs de compilation

Par défaut, les déclencheurs de compilation utilisent le compte de service Cloud Build pour exécuter des compilations, ce qui peut fournir des autorisations de compilation aux utilisateurs qui se servent de déclencheurs pour exécuter une compilation. Tenez compte des implications de sécurité suivantes lorsque vous utilisez des déclencheurs de compilation:

  • Un utilisateur qui n'a pas accès à votre projet Cloud, mais possède un accès en écriture au dépôt associé aux déclencheurs de compilation du projet, sera autorisé à modifier le code en cours de création.
  • Si vous utilisez des déclencheurs de demande d'extraction GitHub, tout utilisateur disposant d'un accès en lecture au dépôt peut envoyer une demande d'extraction, qui peut exécuter une compilation comprenant des modifications du code de la demande d'extraction. Pour savoir comment désactiver ce comportement pour les déclencheurs de demande d'extraction GitHub, consultez la page Créer des déclencheurs GitHub.

Une bonne pratique de sécurité consiste à créer un compte de service avec uniquement les rôles requis pour votre déclencheur. Pour en savoir plus, consultez la section Configurer des comptes de service spécifiés par l'utilisateur. Pour en savoir plus sur le compte de service Cloud Build et les autorisations associées, consultez la section Compte de service Cloud Build.

Étapes suivantes