Automatiser les compilations en réponse aux événements de webhook

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 webhook pour automatiser les compilations en réponse aux événements de webhook.

Avant de commencer

  • Activez les API Cloud Build et Secret Manager.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer les API

  • Pour utiliser les commandes gcloud sur cette page, installez Google Cloud CLI.

  • Si votre déclencheur Webhook utilise un dépôt Cloud Build comme source, assurez-vous de bien connaître les dépôts Cloud Build.

Créer des déclencheurs de webhook

Console

Pour créer un déclencheur de webhook à l'aide de la console Google Cloud  :

  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.

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

      • Si le fichier de configuration de compilation associé au déclencheur spécifie un pool privé, Cloud Build utilise ce pool privé pour exécuter votre compilation. Dans ce cas, la région que vous spécifiez dans votre déclencheur doit correspondre à celle dans laquelle vous avez créé votre pool privé.
      • Si le fichier de configuration de compilation associé au déclencheur ne spécifie pas de pool privé, Cloud Build utilise le pool par défaut pour exécuter votre compilation dans la même région que 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. Vous aurez besoin d'un secret pour authentifier les événements webhook entrants. Vous pouvez créer un secret ou utiliser un secret existant. Ce secret est différent de celui associé à votre clé SSH.

      Pour créer un secret :

      1. Sélectionnez Utiliser un nouveau secret (généré par Cloud Build).

      2. Cliquez sur Créer un secret.

        La boîte de dialogue 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 un secret existant ou en créer un.
      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, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Pour en savoir plus, consultez 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 n'en avez pas encore.

        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.

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

    • Source (facultatif) : si vous spécifiez une configuration de compilation intégrée, vous n'avez pas besoin de spécifier de source. Sinon, procédez comme suit :

      • Génération de dépôts : sélectionnez 2e génération.

      • Dépôt : dans la liste des dépôts disponibles, sélectionnez celui à partir duquel vous souhaitez effectuer la compilation. La région de votre dépôt doit correspondre à celle de votre déclencheur.

      • Branche ou tag : spécifiez une expression régulière à laquelle faire correspondre la valeur de la branche ou du tag. Pour en savoir plus sur la syntaxe des expressions régulières acceptables, consultez la page Syntaxe RE2.

      • Contrôle des commentaires : si vous avez sélectionné Demande d'extraction comme événement, choisissez l'une des options suivantes pour contrôler si le déclencheur appelle automatiquement une compilation :

        • Obligatoire, sauf pour les propriétaires et les collaborateurs : lorsqu'une demande d'extraction est créée ou mise à jour par un propriétaire ou un collaborateur du dépôt, les compilations sont exécutées automatiquement. Si un contributeur externe lance l'action, les compilations ne sont exécutées qu'après que le propriétaire ou le collaborateur a ajouté /gcbrun à la demande d'extraction d'extraction.

        • Obligatoire : lorsqu'une demande d'extraction est créée ou mise à jour par un contributeur, les compilations ne sont exécutées qu'après que le propriétaire ou le collaborateur a ajouté /gcbrun à la demande d'extraction d'extraction. Les compilations sont exécutées chaque fois qu'une modification est apportée à une demande d'extraction;extraction.

        • Non requis : lorsqu'une demande d'extraction est créée ou mise à jour par un contributeur, les compilations sont exécutées automatiquement.

    • 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 buildpacks. 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 la consoleGoogle Cloud à 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.

  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 builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Où :

  • TRIGGER_CONFIG_PATH est le chemin d'accès à un fichier de configuration de déclencheur. Si vous utilisez un fichier de configuration de déclencheur, les champs name, description, region, secret, service-account, subscription-filter et substitution doivent rester non définis. Pour en savoir plus, consultez BuildTrigger dans la documentation de référence Cloud Build.
  • TRIGGER_NAME correspond au nom de votre déclencheur.
  • DESCRIPTION (facultatif) est une description de votre déclencheur.
  • REGION est la région de votre déclencheur. Cette valeur doit être une région autre que "global".
  • SECRET_NAME est le nom de votre secret tel qu'il est stocké dans Secret Manager.
  • SECRET_VERSION est la version associée à votre secret tel qu'il est stocké dans Secret Manager.
  • SERVICE_ACCOUNT est le compte de service utilisé pour exécuter toutes les opérations contrôlées par l'utilisateur liées à votre déclencheur de compilation. Si vous ne définissez pas de compte de service, Cloud Build utilise le compte de service Cloud Build par défaut.
  • PROJECT_ID est l'ID de votre projet Google Cloud .
  • CONNECTION_NAME est le nom de votre connexion hôte.
  • REPO_NAME est le nom de votre dépôt.
  • PATH_TO_BUILD_CONFIG est le chemin d'accès à un fichier de configuration de compilation. Utilisez ce paramètre si votre déclencheur fait référence à un fichier de configuration de compilation dans un dépôt Cloud Build. Si vous définissez ce paramètre, vous ne pouvez pas définir de inline-config ni utiliser de paramètres pour un fichier Dockerfile.
  • PATH_TO_INLINE_BUILD_CONFIG est le chemin d'accès à une configuration de compilation intégrée. Utilisez ce paramètre si le déclencheur fait référence à un fichier de configuration de compilation local. Si vous définissez ce paramètre, vous ne pouvez pas définir de build-config ni utiliser de paramètres pour un fichier Dockerfile.
  • DOCKERFILE est le chemin d'accès à un fichier Dockerfile. Utilisez ce paramètre si votre déclencheur fait référence à un fichier Dockerfile. Si vous définissez des paramètres Dockerfile, vous ne pouvez pas définir de build-config ni de inline-config.
  • DOCKERFILE_DIR est le répertoire du fichier Dockerfile.
  • DOCKERFILE_IMAGE est le nom de l'image Docker que Cloud Build crée.
  • BRANCH_NAME est le nom de votre branche si vous souhaitez configurer votre déclencheur pour qu'il se compile sur une branche. Si vous définissez ce paramètre, vous ne pouvez pas définir de tag.
  • TAG_NAME est le nom de votre tag si vous souhaitez configurer votre déclencheur pour qu'il effectue une compilation sur un tag. Si vous définissez ce paramètre, vous ne pouvez pas définir de branch.
  • SUBSTITUTION (facultatif) sont des paramètres à substituer dans la spécification de compilation. Exemple : _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
  • FILTER (facultatif) est une expression de filtre CEL pour le déclencheur, par exemple '_SUB_ONE == "prod"'.
  • (Facultatif) Lorsque --require-approval est présent dans la commande, Cloud Build exige une approbation manuelle pour les builds déclenchés.

Appeler un événement webhook

Utilisez la commande suivante pour appeler un événement de webhook :

curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

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

Lorsque vous configurez votre secret lors de la création d'un déclencheur de webhook, Cloud Build attribue automatiquement le rôle Accesseur de secrets Secret Manager aux comptes de service qui en ont besoin dans la plupart des cas. Toutefois, si vous utilisez un secret existant, vous devrez peut-être aussi attribuer manuellement le rôle Accesseur de secrets Secret Manager à votre compte de service Cloud Build :

  1. Ouvrez la page IAM dans la console Google Cloud  :

    Ouvrir la page IAM

  2. Facultatif : Pour afficher les comptes fournis par Google, cochez la case Inclure les attributions de rôles fournies par Google.

  3. Prenez note du compte de service de compilation auquel vous souhaitez accorder le rôle.

  4. Ouvrez la page Secret Manager dans la console Google Cloud  :

    Ouvrir la page Secret Manager

  5. Cliquez sur le nom de votre secret.

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

    1. Cliquez sur l'onglet Autorisations.

    2. Cliquez sur Accorder l'accès.

      Le panneau Accorder l'accès s'affiche.

    3. Dans la section Ajouter des comptes principaux, ajoutez l'adresse e-mail associée au compte de service de compilation.

    4. Dans la section Attribuer des rôles, sélectionnez Secret Manager > Accesseur de secrets Secret Manager.

    5. Cliquez sur Enregistrer.

(Facultatif) Obtenir une clé API

Pour authentifier un événement webhook entrant, vous avez besoin d'une clé API. Cette clé API fait partie du secret que vous choisissez lorsque vous configurez votre déclencheur de webhook. Si vous ne disposez pas encore d'une clé API ou si Cloud Build n'a pas pu en récupérer une lors de la configuration de votre secret dans la console Google Cloud , vous pouvez créer manuellement une clé API :

Pour obtenir une clé API:

  1. Ouvrez la page Identifiants dans la console Google Cloud  :

    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.

Étapes suivantes