Créer des déclencheurs de webhooks

Cloud Build vous permet de définir des déclencheurs de webhook, qui peuvent authentifier et accepter les événements de webhook entrants. Ces événements, envoyés à une URL personnalisée, vous permettent de connecter directement des systèmes externes et des systèmes de gestion de code source externes tels que Bitbucket.com, Bitbucket Server ou GitLab à Cloud Build via des événements de webhook.

Avec les déclencheurs de webhook, vous pouvez définir un fichier de configuration de compilation intégré plutôt que de spécifier une source lors de la création de votre déclencheur. La configuration de compilation intégrée vous permet de contrôler les opérations Git et de définir le reste de votre compilation.

Cette page explique comment créer des déclencheurs de webhooks.

Avant de commencer

  • Activer les API Cloud Build and Secret Manager.

    Activer les API

  • Pour utiliser les commandes gcloud sur cette page, installez le SDK Cloud.

Créer des déclencheurs de webhooks

Console

Pour créer un déclencheur de webhook à l'aide de Google Cloud Console, procédez comme suit:

  1. Ouvrez la page Déclencheurs :

    Ouvrir la page Déclencheurs de compilation

  2. Sélectionnez votre projet en haut de la page, puis cliquez sur Ouvrir.

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

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

    • Nom : nom de votre déclencheur.
    • Description (facultatif) : description de votre déclencheur.
    • Événement: sélectionnez Événement de webhook pour configurer votre déclencheur de sorte qu'il lance des compilations en réponse aux événements de webhook entrants.
    • URL de webhook: utilisez l'URL du webhook pour authentifier les événements webhooks entrants.

      • Secret: vous aurez besoin d'un secret pour authentifier les événements webhook entrants. Vous pouvez créer un secret ou utiliser un secret existant.

        Pour créer un secret:

        1. Sélectionnez Créer.
        2. Cliquez sur Créer un secret.

          La fenêtre pop-up Créer un secret de webhook s'affiche.

        3. Dans le champ Nom du secret, saisissez le nom du secret.

        4. Cliquez sur Créer un secret pour enregistrer votre secret, qui sera automatiquement créé et stocké dans Secret Manager.

        Pour utiliser un secret existant, procédez comme suit:

        1. Sélectionnez Utiliser existant.
        2. Dans le champ Secret, sélectionnez le nom du secret que vous souhaitez utiliser dans le menu déroulant ou suivez les instructions pour ajouter un secret par ID de ressource.
        3. Dans le champ Version du secret, sélectionnez la version de votre secret dans le menu déroulant.

        Si vous utilisez un secret existant, vous devrez peut-être attribuer manuellement le rôle "Accesseur de secrets" de Secret Manager à votre compte de service Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Pour en savoir plus, consultez la section Attribuer le rôle Secret Manager à votre compte de service.

      Une fois le secret créé ou sélectionné, un aperçu d'URL de webhook s'affiche. Votre URL contiendra une clé API générée par Cloud Build et votre secret. Si Cloud Build ne parvient pas à récupérer votre clé API, vous pouvez l'ajouter manuellement à l'URL ou apprendre à obtenir une clé API si vous ne disposez pas de pour l'instant.

      Vous pouvez utiliser l'URL pour appeler un événement de webhook en effectuant une requête HTTP à l'aide de la méthode POST.

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

      Une fois ces étapes effectuées, le rôle Accesseur de secrets de Secret Manager sera automatiquement attribué à votre compte de service Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Si vous ne voyez pas ce rôle automatiquement ajouté à votre compte de service, suivez les étapes décrites dans la section Attribuer le rôle Secret Manager à votre compte de service.

    • Source (facultatif): sélectionnez le dépôt à compiler lorsque le déclencheur Webhook est exécuté. Si vous spécifiez une configuration de compilation intégrée, vous n'avez pas besoin de spécifier la source suivante.

    • Révision (facultatif): sélectionnez la branche ou le tag à compiler lorsque le déclencheur Webhook est exécuté. Si vous spécifiez une configuration de compilation intégrée, vous n'avez pas besoin de spécifier les révisions suivantes.

      • Branche (facultatif) : définissez un déclencheur pour démarrer une compilation sur cette branche. Vous devez spécifier une valeur littérale. Les expressions régulières ne sont pas acceptées.
      • Tag (facultatif) : définissez un déclencheur pour démarrer une compilation sur ce tag. Vous devez spécifier une valeur littérale. Les expressions régulières ne sont pas acceptées.
    • 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. Si vous n'avez pas spécifié de dépôt source, vous devez sélectionner un fichier de configuration de compilation intégré comme option de configuration.

      • 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.

        • Repository (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 packs de création. 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 Ouvrir l'éditeur pour écrire votre fichier de configuration de compilation dans Google Cloud Console à l'aide d'une syntaxe YAML ou JSON. Cliquez sur OK pour enregistrer la configuration de compilation.

      Dans l'exemple suivant, les journaux du fichier de configuration de compilation intégrée renvoient "hello world":

       steps:
       - name: 'ubuntu'
         args: ['echo', 'hello world']
      
    • Substitutions (facultatif): si vous avez sélectionné le fichier de configuration de compilation comme option de configuration de compilation ou que vous avez créé un fichier de configuration de compilation intégré, vous pouvez choisir de définir des Variables de substitution spécifiques au déclencheur à l'aide de ce champ. Vous pouvez également obtenir des données à l'aide de liaisons de charge utile lors de la définition des valeurs des variables de substitution.

    • Filtres (facultatif): vous pouvez créer une règle dans un déclencheur qui détermine si votre déclencheur exécutera une compilation en fonction de vos variables de substitution.

      Pour voir un exemple de syntaxe de filtrage que vous pouvez appliquer à vos déclencheurs de webhook, consultez la section Utiliser le langage CEL pour filtrer les événements de compilation.

  5. Cliquez sur Créer pour créer votre déclencheur de compilation.

gcloud

Pour créer un déclencheur webhook, procédez comme suit:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Où :

  • TRIGGER_NAME correspond au nom de votre déclencheur.
  • PATH_TO_REPO est le chemin d'accès au dépôt sur lequel appeler une compilation. Exemple :https://www.github.com/owner/repo
  • PATH_TO_SECRET est le chemin d'accès au secret stocké dans Secret Manager. Exemple : projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG est le chemin d'accès à votre fichier de configuration de compilation intégré si vous utilisez --inline-config.
  • TAG_NAME est le nom de votre tag si vous souhaitez configurer votre déclencheur pour qu'il effectue une compilation sur un tag.
  • PATH_TO_BUILD_CONFIG est le chemin d'accès de votre fichier de configuration de compilation si vous utilisez --build-config.
  • BRANCH_NAME est le nom de votre branche si vous souhaitez configurer votre déclencheur pour qu'il se compile sur une branche.

(Facultatif) Obtenir une clé API

Vous aurez besoin d'une clé API pour authentifier votre événement webhook entrant.

Pour obtenir une clé API:

  1. Ouvrez la page Identifiants dans Google Cloud Console:

    Ouvrez la page Identifiants.

  2. Cliquez sur Créer des identifiants.

  3. Cliquez sur Clé API.

    Une boîte de dialogue contenant la clé API s'affiche. Prenez note de votre clé API.

  4. Si vous souhaitez limiter votre clé pour les applications de produits, cliquez sur Restreindre la clé pour effectuer les étapes supplémentaires permettant de sécuriser votre clé. Sinon, cliquez sur Fermer.

    Pour savoir comment restreindre votre clé, consultez la section Appliquer des restrictions de clé API.

(Facultatif) Attribuer le rôle "Secret Manager" à votre compte de service

Cloud Build attribue automatiquement le rôle Accesseur de secrets de Secret Manager aux comptes de service nécessitant ce rôle lors de la configuration du secret. Si ce rôle n'est pas automatiquement attribué au compte de service nécessaire, procédez comme suit pour l'ajouter manuellement afin que votre compte de service ait accès à votre secret:

  1. Ouvrez la page "IAM" dans Cloud Console :

    Ouvrir la page IAM

  2. Prenez note du compte de service Cloud Build auquel vous souhaitez accorder le rôle.

  3. Ouvrez la page Secret Manager dans Cloud Console:

    Ouvrir la page Secret Manager

  4. Cliquez sur le nom de votre secret.

    La page Informations détaillées sur le secret s'affiche.

    1. Cliquez sur l'onglet Autorisations dans le panneau d'informations de droite.

    2. Cliquez sur Ajouter un compte principal.

    3. Dans la section Nouveau compte principal, ajoutez l'adresse e-mail associée à votre compte de service Cloud Build.

    4. Dans la section Sélectionner un rôle, sélectionnez Secret Manager > Accesseur de secrets Secret Manager.

    5. Cliquez sur Ajouter.

Utiliser le CEL pour filtrer les événements de compilation

Cloud Build utilise le CEL avec la variable, build, sur les champs répertoriés dans la ressource Compilation afin d'accéder aux champs associés à votre événement de compilation, tels que votre ID de déclencheur, votre liste d'images, ou vos valeurs de substitution. Vous pouvez utiliser la chaîne filter pour filtrer les événements de compilation dans votre fichier de configuration de compilation à l'aide de n'importe quel champ répertorié dans la ressource Compilation. Pour trouver la syntaxe exacte associée à votre champ, consultez le fichier cloudbuild.proto.

Filtrer par ID de déclencheur

Pour filtrer par ID de déclencheur, spécifiez la valeur de votre ID de déclencheur dans le champ filter à l'aide de build.build_trigger_id, où trigger-id est votre ID de déclencheur sous forme de chaîne :

filter: build.build_trigger_id == trigger-id

Filtrer par état

Pour filtrer par état, spécifiez l'état de la compilation que vous souhaitez filtrer dans le champ filter à l'aide de build.status.

L'exemple suivant montre comment filtrer les événements de compilation dotés de l'état SUCCESS à l'aide du champ filter :

filter: build.status == Build.Status.SUCCESS

Vous pouvez également filtrer les compilations présentant des états différents. L'exemple suivant montre comment filtrer les événements de compilation dont l'état est SUCCESS, FAILURE ou TIMEOUT à l'aide du champ filter :

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Pour afficher des valeurs d'état supplémentaires que vous pouvez filtrer, consultez la section État dans la documentation de référence sur les ressources de compilation.

Filtrer par tag

Pour filtrer par tag, spécifiez la valeur de votre tag dans le champ filter à l'aide de build.tags, où tag-name est le nom de votre tag :

filter: tag-name in build.tags

Vous pouvez appliquer un filtre en fonction du nombre de tags spécifiés dans votre événement de compilation à l'aide de size. Dans l'exemple suivant, le champ filter filtre les événements de compilation comportant exactement deux tags spécifiés, avec un tag spécifié en tant que v1 :

filter: size(build.tags) == 2 && "v1" in build.tags

Filtrer par images

Pour filtrer par images, spécifiez la valeur de votre image dans le champ filter à l'aide de build.images, où image-name est le nom complet de votre image, tel que répertorié dans Container Registry, comme par exemple gcr.io/example/image-one :

filter: image-name in build.images

Dans l'exemple suivant, les filtres filter sont appliqués aux événements de compilation dont le nom d'image spécifié est gcr.io/example/image-one ou gcr.io/example/image-two :

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Filtrer par date et heure

Vous pouvez filtrer les événements de compilation en fonction de la date et l'heure de création, de début ou de fin d'une compilation en spécifiant l'une des options suivantes dans votre champ filter : build.create_time, build.start_time ou build.finish_time

Dans l'exemple suivant, le champ filter utilise timestamp pour filtrer les événements de compilation dont la date et l'heure de requête pour créer la compilation sont fixées au 20 juillet 2020 à 6h00 :

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Vous pouvez également filtrer les événements de compilation par comparaisons horaires. Dans l'exemple suivant, le champ filter utilise timestamp pour filtrer les événements de compilation dont le début est compris entre le 20 juillet 2020 à 6h00 et le 30 juillet 2020 à 6h00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Pour en savoir plus sur la façon dont les fuseaux horaires sont exprimés dans le CEL, consultez la définition de langage pour les fuseaux horaires.

Pour filtrer par durée de compilation, vous pouvez utiliser duration pour comparer les horodatages. Dans l'exemple suivant, le champ filter utilise duration pour filtrer les événements de compilation dont la compilation a duré au moins cinq minutes :

filter: build.finish_time - build.start_time >= duration("5m")

Filtrer par substitution

Vous pouvez filtrer par substitution en spécifiant la variable de substitution dans le champ filter à l'aide de build.substitutions. Dans l'exemple suivant, le champ filter répertorie les compilations contenant la variable de substitution substitution-variable et vérifie si substitution-variable correspond à l'élément substitution-value spécifié :

filter: build.substitutions[substitution-variable] == substitution-value

Où :

  • substitution-variable est le nom de votre variable de substitution.
  • substitution-value est le nom de votre valeur de substitution.

Vous pouvez également filtrer par valeur de variable de substitution par défaut. Dans l'exemple suivant, le champ filter répertorie les compilations portant le nom de branche master et les compilations portant le nom de dépôt github.com/user/my-example-repo. Les variables de substitution par défaut BRANCH_NAME et REPO_NAME sont transmises sous forme de clés à build.substitutions :

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Si vous souhaitez filtrer les chaînes à l'aide d'expressions régulières, vous pouvez utiliser la fonction matches intégrée. Dans l'exemple ci-dessous, le champ filter filtre les compilations dont l'état est FAILURE ou TIMEOUT, et qui disposent également d'une variable de substitution de compilation TAG_NAME avec une valeur correspondant à l'expression régulière v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Pour afficher la liste des valeurs de substitution par défaut, consultez la section Utiliser des substitutions par défaut.

Étape suivante