Creare repository da Bitbucket Cloud

Questa pagina spiega come creare build su Bitbucket Cloud utilizzando i trigger webhook.

Prima di iniziare

  • Abilita le API Cloud Build and Secret Manager.

    Abilita le API

  • Per utilizzare i comandi gcloud in questa pagina, installa l'interfaccia a riga di comando di Google Cloud.

Configurazione

Prima di creare un trigger webhook per creare su Bitbucket Cloud, devi creare una chiave SSH per autenticare la connessione a Bitbucket Cloud. Quando crei un trigger senza un repository associato e accedi al codice su un sistema di gestione del codice sorgente esterno, ad esempio Bitbucket Cloud, devi recuperare la chiave SSH nella configurazione della build incorporata.

In questa sezione viene spiegato come creare e archiviare la chiave SSH prima di creare un attivatore webhook.

Creazione di una chiave SSH

Per accedere al codice su Bitbucket Cloud, devi recuperare una chiave SSH nella configurazione della build incorporata.

Per creare una chiave SSH:

  1. Apri una finestra del terminale.

  2. Crea una nuova directory denominata working-dir e accedi alla directory:

    mkdir working-dir
    cd working-dir
    
  3. Crea una nuova chiave SSH Bitbucket Cloud, in cui bitbucket.org è l'URL del tuo repository Bitbucket Cloud:

    ssh-keygen -t rsa -b 4096 -N '' -C bitbucket.org -f id_bitbucket
    

    Il comando crea una nuova chiave SSH in working-dir/id_bitbucket senza una passphrase per la tua chiave SSH. Cloud Build non può utilizzare la tua chiave SSH se è protetta con una passphrase.

Aggiunta della chiave di accesso SSH pubblica su Bitbucket Cloud

Per proteggere le operazioni che altri sistemi eseguono sui tuoi repository gestiti in Bitbucket Cloud, devi aggiungere la chiave di accesso SSH pubblico su Bitbucket Cloud e concedere le tue autorizzazioni di lettura alla chiave. Per informazioni su come aggiungere la chiave, vedi Aggiungere chiavi di accesso.

Creazione e archiviazione delle credenziali in Secret Manager

Quando crei una chiave SSH, viene creato un file id_bitbucket nel tuo ambiente locale. Poiché questo file contiene informazioni sensibili associate all'autenticazione, devi archiviarlo in Secret Manager prima di utilizzarlo per richiamare una build.

Oltre al secret utilizzato durante la creazione di un attivatore webhook, dovrai creare un secret in Secret Manager per convalidare e autorizzare gli eventi webhook in arrivo in Cloud Build.

Per creare e archiviare le tue credenziali in Secret Manager:

  1. Vai alla pagina di Secret Manager nella console:

    Vai alla pagina Secret Manager

  2. Nella pagina Secret Manager (Gestione secret), fai clic su Create Secret (Crea secret).

  3. Nella pagina Crea secret, in Nome, inserisci un nome per il secret.

  4. Nel campo Valore secret, inserisci un nome per il secret o carica un file.

    Per caricare il file della chiave SSH, fai clic su Carica per includere il file working-dir/id_bitbucket.

  5. Non modificare la sezione Regioni.

  6. Fai clic sul pulsante Crea secret.

Dopo aver creato il secret, Google Cloud Console concederà automaticamente il ruolo Secret Manager Secret Accesser al tuo account di servizio Cloud Build, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Se non vedi questo ruolo nel tuo account di servizio, completa i seguenti passaggi descritti in Concedere il ruolo di Secret Manager all'account di servizio.

Ora che hai archiviato la tua chiave SSH, puoi anche eliminarla dal tuo ambiente e eseguendo il seguente comando:

rm id_bitbucket*

Ora è tutto pronto per la creazione del trigger di webhook.

Creazione di trigger webhook

console

Per creare un trigger webhook che richiami le build da Bitbucket Cloud utilizzando Google Cloud Console:

  1. Apri la pagina Trigger:

    Apri la pagina Trigger di build

  2. Seleziona il progetto nella parte superiore della pagina e fai clic su Apri.

  3. Fai clic su Crea trigger.

  4. Inserisci le seguenti impostazioni di attivazione:

    • Nome: un nome per l'attivatore.
    • Area geografica: seleziona l'area geografica per l'attivatore.

      • Se selezioni global come area geografica, Cloud Build utilizza il pool predefinito per eseguire la tua build.
      • Se selezioni un'area geografica non globale e il file di configurazione di compilazione associato al trigger specifica un pool privato, Cloud Build utilizza il pool privato per eseguire la build. In questo caso, l'area geografica specificata nel trigger deve corrispondere a quella in cui hai creato il pool privato.
      • Se selezioni un'area geografica non globale e il file di configurazione di compilazione associato al trigger non specifica un pool privato, Cloud Build utilizza il pool predefinito per eseguire la tua build nella stessa area geografica del trigger.
    • (Facoltativo) Descrizione: una descrizione per l'attivatore.

    • Evento: seleziona Evento webhook per configurare il trigger per avviare le build in risposta agli eventi webhook in arrivo.

    • URL webhook: utilizza l'URL webhook per autenticare gli eventi webhook in entrata.

      • Secret: ti servirà un secret per autenticare gli eventi webhook in entrata. Puoi creare un nuovo secret o utilizzarne uno esistente.

        Per creare un nuovo secret:

        1. Seleziona Crea nuova.
        2. Fai clic su Crea secret.

          Verrà visualizzata la finestra popup Crea un secret webhook.

        3. Nel campo Nome secret, inserisci un nome per il secret.

        4. Fai clic su Crea secret per salvare il secret, che verrà creato e archiviato automaticamente in Secret Manager.

        Per utilizzare un secret esistente:

        1. Seleziona Utilizza esistente.
        2. Nel campo Secret, seleziona il nome del secret che vuoi utilizzare dal menu a discesa o segui le istruzioni per aggiungere un secret in base all'ID risorsa.
        3. Nel campo Versione del secret, seleziona la tua versione del secret dal menu a discesa.

        Se utilizzi un secret esistente, potresti dover concedere manualmente il ruolo Secret Accessor Secret Manager al tuo account di servizio Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Per saperne di più, vedi Concedere il ruolo di Secret Manager al tuo account di servizio.

      Dopo aver creato o selezionato il secret, vedrai un'anteprima dell'URL webhook. L'URL conterrà una chiave API generata da Cloud Build e dal tuo secret. Se Cloud Build non è in grado di recuperare la tua chiave API, puoi aggiungerla manualmente all'URL o scoprire come ottenere una chiave API se non ne hai ancora una.

      Puoi utilizzare l'URL per richiamare un evento webhook effettuando una richiesta HTTP tramite il metodo 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 "{}"
      

      Per informazioni su come utilizzare l'URL durante la creazione di un webhook in Bitbucket Cloud, consulta Creazione di un webhook in Bitbucket Cloud.

    • (Facoltativo) Origine: il repository da creare quando viene eseguito il trigger webhook. Lascia vuoto questo campo. In questo esempio, la configurazione di compilazione è una configurazione di compilazione in linea, quindi non è necessaria un'origine.

    • Configurazione: crea una configurazione di compilazione in linea in Google Cloud Console.

      Nell'esempio seguente, la configurazione di compilazione incorporata autentica la tua connessione a Bitbucket Cloud utilizzando la tua chiave SSH e accede al repository specificato. In seguito, controlla il commit che ha richiamato il 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 bitbucket.org > /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'
          - 'git@bitbucket.org/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
      

      Dove:

      • BITBUCKET_REPO è il percorso del tuo repository Bitbucket.
      • PATH_TO_SECRET_VERSION è il percorso della tua versione del secret memorizzato in Secret Manager. Questo è il secret che contiene la tua chiave SSH. Ad esempio, projects/project-id/secrets/secret-name/versions/1
      • SSHKEY è il nome della variabile di ambiente utilizzata in questo caso per archiviare il percorso del secret.
    • (Facoltativo) Sostituzioni: puoi scegliere di definire variabili di sostituzione specifiche per l'attivatore utilizzando questo campo.

      In questo esempio, supponiamo di voler cercare un nome di un ramo specifico associato a un ID commit e di passare poi al nome del ramo nella definizione di build. Per ottenere questi dati, puoi creare variabili di sostituzione utilizzando le associazioni dei payload per salvare il nome del ramo.

      Specifica le seguenti variabili e valori di seguito:

      Nome variabile Valore variabile
      _BRANCH $(body.push.changes[0].new.name)
      _TO_SHA $(body.push.changes[0].new.target.hash)

      Per visualizzare il payload associato agli eventi di Bitbucket Cloud, consulta la sezione Payload degli eventi.

    • (Facoltativo) Filtri: puoi creare una regola all'interno di un attivatore che determini se l'attivatore eseguirà o meno una build in base alle variabili di sostituzione.

      Poiché vuoi che il trigger esegua la build se il nome del ramo corrisponde a main, puoi utilizzare l'operatore "=={quot; per verificare la corrispondenza esatta. Puoi anche utilizzare la parola chiave "corrisponde a" se vuoi trovare una corrispondenza in base a un'espressione regolare.

      Specifica i seguenti filtri come filtri:

      • _BRANCH == refs/heads/main

      Per visualizzare un esempio di sintassi per i filtri che puoi applicare ai tuoi trigger webhook, consulta la sezione Utilizzo della CEL per filtrare gli eventi di build.

  5. Fai clic su Crea per creare il trigger di build.

gcloud

Per creare un trigger webhook che richiami build da Bitbucket Cloud:

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --secret=PATH_TO_SECRET \
       --substitutions='' \
       --filter='' \
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG \ # or --repo=PATH_TO_REPO
       --branch=BRANCH_NAME #  or --tag=TAG_NAME

Dove:

  • TRIGGER_NAME è il nome del tuo attivatore.
  • PATH_TO_SECRET è il percorso del secret come memorizzato in Secret Manager. Ad esempio, projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG è il percorso della configurazione della build in linea. Anche se la configurazione della build è archiviata in linea nell'attivatore che stai creando, il percorso di configurazione qui viene estratto da un file locale.
  • PATH_TO_REPO è il percorso del repository per richiamare una build. Ad esempio, https://bitbucket.org/username/repo-slug. L'URL del tuo repository deve essere un repository connesso di Cloud Build.

  • BRANCH_NAME è il nome del ramo se vuoi impostare il trigger per creare un ramo.

  • TAG_NAME è il nome del tag se vuoi impostare l'attivatore per la creazione di un tag.

Creazione di un webhook in Bitbucket Cloud

Affinché Bitbucket Cloud effettui richieste a Cloud Build, devi creare un webhook in Bitbucket Cloud seguendo le istruzioni riportate nella sezione Creare e attivare un webhook.

Ora, ogni volta che gli aggiornamenti al tuo repository corrispondono all'evento di trigger che hai specificato nel webhook, una build viene richiamata automaticamente dai trigger webhook di Cloud Build.

Passaggi successivi