Créer des dépôts depuis Bitbucket Server

Cette page explique comment effectuer des compilations sur Bitbucket Server à l'aide de déclencheurs de webhook.

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.

Configuration

Avant de créer un déclencheur de webhook à compiler sur Bitbucket Server, vous devez créer une clé SSH afin d'authentifier votre connexion à Bitbucket Server. Lorsque vous créez un déclencheur sans dépôt associé et accédez à votre code sur un système de gestion de code source externe, tel que Bitbucket Server, vous devez récupérer votre clé SSH dans votre configuration de compilation intégrée.

Cette section explique comment créer et stocker votre clé SSH avant de créer un déclencheur webhook.

Créer une clé SSH

Pour accéder à votre code sur Bitbucket Server, vous devez récupérer une clé SSH dans votre configuration de compilation intégrée.

Pour créer une clé SSH:

  1. Ouvrez une fenêtre de terminal.

  2. Créez un répertoire nommé working-dir et accédez-y :

    mkdir working-dir
    cd working-dir
    
  3. Créez une clé SSH Bitbucket Server, où BITBUCKET_SERVER_HOST/REPOSITORY est l'URL de votre dépôt Bitbucket Server:

    ssh-keygen -t rsa -b 4096 -N '' -C BITBUCKET_SERVER_HOST/REPOSITORY -f id_bitbucket
    

    La commande crée une clé SSH dans working-dir/id_bitbucket sans phrase secrète pour votre clé SSH. Cloud Build ne peut pas utiliser votre clé SSH si elle est protégée par une phrase secrète.

Activer l'accès SSH sur Bitbucket Server

Vous devrez activer l'accès SSH sur votre serveur Bitbucket pour permettre aux utilisateurs de votre serveur d'ajouter leurs propres clés SSH et d'utiliser ces clés SSH pour sécuriser les opérations Git entre leur ordinateur et l'instance Bitbucket Server. Pour apprendre à utiliser SSH avec Bitbucket Server, consultez la page Activer l'accès SSH aux dépôts Git dans Bitbucket Server.

Ajouter votre clé d'accès SSH publique sur Bitbucket Server

Pour sécuriser les opérations effectuées par d'autres systèmes sur vos dépôts gérés dans Bitbucket Server, vous devez ajouter votre clé d'accès SSH publique sur Bitbucket Server et accorder à votre clé les autorisations de Lecture. Pour savoir comment ajouter votre clé, consultez la section Clés d'accès SSH pour une utilisation du système.

Créer et stocker vos identifiants dans Secret Manager

Lorsque vous créez une clé SSH, un fichier id_bitbucket est créé dans votre environnement local. Comme ce fichier contient des informations sensibles associées à l'authentification, vous devez le stocker dans Secret Manager avant de l'utiliser pour appeler une compilation.

En plus du secret utilisé lors de la création d'un déclencheur de webhook, vous devez également créer un secret dans Secret Manager pour valider et autoriser les événements de webhook entrants dans Cloud Build.

Pour créer et stocker vos identifiants dans Secret Manager:

  1. Accédez à la page Secret Manager dans Cloud Console :

    Accéder à la page Secret Manager

  2. Sur la page Secret Manager, cliquez sur Créer un secret.

  3. Sur la page Créer un secret, sous Nom, saisissez le nom du secret.

  4. Dans le champ Valeur du secret, saisissez le nom du secret ou importez un fichier.

    Pour importer votre fichier de clé SSH, cliquez sur Upload (Importer) afin d'inclure votre fichier working-dir/id_bitbucket.

  5. Ne modifiez pas la section Régions.

  6. Cliquez sur le bouton Créer un secret pour créer votre secret.

Après avoir créé votre secret, Google Cloud Console attribue automatiquement le rôle Accesseur de secrets de Secret Manager à votre compte de service Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Si ce rôle ne s'affiche pas sur votre compte de service, suivez les étapes décrites dans la section Attribuer le rôle Secret Manager à votre compte de service.

Maintenant que vous avez stocké votre clé SSH, vous pouvez également supprimer la clé SSH de votre environnement en exécutant la commande suivante:

rm id_bitbucket*

Vous êtes maintenant prêt à créer votre déclencheur webhook.

Créer des déclencheurs de webhooks

Console

Pour créer un déclencheur de webhook qui compile à partir de Bitbucket Server à 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 "{}"
      

      Pour savoir comment utiliser l'URL lors de la création d'un webhook dans Bitbucket Server, consultez la page Créer un webhook dans Bitbucket Server.

    • Source (facultatif): dépôt à compiler lorsque le déclencheur de webhook est exécuté. Laissez ce champ vide. Dans cet exemple, la configuration de compilation est une configuration de compilation intégrée. Une source n'est donc pas nécessaire.

    • Configuration: créez une configuration de compilation intégrée dans Google Cloud Console.

      Dans l'exemple suivant, la configuration de compilation intégrée authentifie votre connexion à Bitbucket Server à l'aide de votre clé SSH et accède au dépôt spécifié. Ensuite, il vérifie le commit qui a appelé le webhook.

      steps:
      # first, setup SSH:
      # 1- save the SSH key from Secret Manager to a file
      # 2- add the host key to the known_hosts file
      - name: gcr.io/cloud-builders/git
        args:
          - '-c'
          - |
            echo "$$SSHKEY" > /root/.ssh/id_rsa
            chmod 400 /root/.ssh/id_rsa
            ssh-keyscan -p BITBUCKET_PORT BITBUCKET_HOST > /root/.ssh/known_hosts
        entrypoint: bash
        secretEnv:
          - SSHKEY
        volumes:
          - name: ssh
            path: /root/.ssh
      # second, clone the repository
      - name: gcr.io/cloud-builders/git
        args:
          - clone
          - '-n'
          - 'ssh://BITBUCKET_HOST:BITBUCKET_PORT/BITBUCKET_REPO'
          - .
        volumes:
          - name: ssh
            path: /root/.ssh
      # third, checkout the specific commit that invoked this build
      - name: gcr.io/cloud-builders/git
        args:
          - checkout
          - $_TO_SHA
      availableSecrets:
        secretManager:
        - versionName: PATH_TO_SECRET_VERSION
          env: SSHKEY
      

      Où :

      • BITBUCKET_HOST est le nom d'hôte de votre dépôt Bitbucket.
      • BITBUCKET_PORT est le port SSH de votre dépôt Bitbucket (généralement 7999).
      • BITBUCKET_REPO est le chemin d'accès au dépôt Bitbucket.
      • PATH_TO_SECRET_VERSION est le chemin d'accès à la version de votre secret, tel qu'il est stocké dans Secret Manager. Il s'agit du secret contenant votre clé SSH. Par exemple, projects/project-id/secrets/secret-name/versions/1.
      • SSHKEY est le nom de l'environnement utilisé dans ce cas pour stocker le chemin d'accès à votre secret.
    • Substitutions (facultatives): vous pouvez choisir de définir des variables de substitution spécifiques au déclencheur à l'aide de ce champ.

      Dans cet exemple, supposons que vous souhaitiez surveiller un nom de branche spécifique associé à un ID de commit, puis basculer vers ce nom de branche dans la définition de compilation. Pour obtenir ces données, vous pouvez créer des variables de substitution à l'aide de liaisons de charge utile pour enregistrer le nom de la branche.

      Spécifiez les variables et valeurs suivantes:

      Nom de la variable Valeur de la variable
      _BRANCH $(body.changes[0].refId)
      _TO_SHA $(body.changes[0].toHash)

      Pour afficher la charge utile associée aux événements Bitbucket Server, consultez la section Charge utile de l'événement.

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

      Comme vous souhaitez que le déclencheur exécute une compilation si le nom de la branche correspond à main, vous pouvez utiliser l'opérateur "==" pour rechercher des correspondances exactes. Vous pouvez également utiliser le mot clé "correspondances" si vous souhaitez rechercher des correspondances par expression régulière.

      Spécifiez les filtres suivants:

      • _BRANCH == refs/heads/main

      Pour plus d'exemples de syntaxe sur le 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 de webhook qui compile à partir de Bitbucket Server, exécutez la commande gcloud alpha. Dans l'exemple ci-dessous, le déclencheur est configuré pour répondre aux compilations avec une branche correspondant à refs/heads/main en fonction de la charge utile spécifiée comme définie par la variable de substitution, _BRANCH.

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --subtitutions=\
         _BRANCH='$(body.changes[0].refId)', TO_SHA='$(body.changes[0].refId)'
       --filter='_BRANCH == refs/heads/main'
       --inline-config=PATH_TO_INLINE_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 configuration de compilation intégrée.

  • BRANCH_NAME est le nom de votre branche si vous souhaitez configurer votre déclencheur pour qu'il se compile sur une branche.

Créer un webhook dans Bitbucket Server

Pour que Bitbucket Server envoie des requêtes à Cloud Build, vous devez créer un webhook dans Bitbucket Server en suivant les instructions décrites dans la section Créer des webhooks.

Désormais, chaque fois que les mises à jour de votre dépôt correspondent à l'événement déclencheur que vous avez spécifié dans votre webhook, une compilation est automatiquement appelée par les déclencheurs du webhook Cloud Build.

Étape suivante