Configurare i webhook

Questa pagina descrive come configurare i webhook in Secure Source Manager.

I webhook sono richieste HTTP attivate da un evento in Secure Source Manager e inviate a un URL specificato dall'utente.

Prima di iniziare

  1. Crea un'istanza Secure Source Manager.
  2. Crea un repository Secure Source Manager.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare webhook, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per informazioni sulla concessione dei ruoli Secure Source Manager, consulta Controllo dell'accesso con IAM e Concedere agli utenti l'accesso all'istanza.

Configurare un webhook

Console

  1. Nell'interfaccia web di Secure Source Manager, vai al repository per cui vuoi creare un webhook.
  2. Fai clic su Impostazioni.
  3. Fai clic su Webhook e poi su Aggiungi webhook.

  4. Nel campo ID hook, inserisci un ID per il webhook.

  5. Nel campo URL di destinazione, inserisci l'URL webhook. Ad esempio, se vuoi attivare una build in Jenkins, puoi configurare un trigger webhook e poi inserire qui l'URL del trigger Jenkins per attivare la build in Jenkins.

  6. Nella sezione Attiva su, seleziona una delle seguenti opzioni:

    • Push: per attivare un push nel repository.
    • Stato della richiesta di pull modificato: per attivare un evento in caso di modifica dello stato della richiesta di pull.

  7. Configura l'autenticazione webhook utilizzando una stringa di query sensibile o l'autenticazione delaccount di serviziot:

    • Stringa di query sensibile:

      La stringa di query sensibile è costituita dai valori key e secret dell'URL webhook, inclusi i prefissi key= e secret=. Per configurare l'autorizzazione della stringa di query sensibile, devi rimuovere questi valori dall'URL webhook e aggiungerli al campo Stringa di query sensibile:

      1. Elimina ? dall'URL del webhook.
      2. Copia la parte rimanente dell'URL, a partire da key=.
      3. Incolla questa parte nel campo Stringa di query sensibile.
      4. Elimina la stessa parte dall'URL del webhook.

      Ad esempio, dato il seguente URL: https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

      La stringa di query sensibile sarebbe: key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

    • Autenticazione del service account:

      1. Verifica che il repository disponga di un account di servizio con i ruoli IAM definiti per l'autenticazione delaccount di serviziot in Ruoli richiesti.
      2. Seleziona Enable account di servizio authentication (Attiva l'autenticazione del service account).

  8. Se hai selezionato Push, puoi inserire una lista consentita per gli eventi push nel campo Filtro ramo.

    Il campo Filtro ramo utilizza il pattern glob e solo le operazioni sui rami corrispondenti attiveranno un trigger di build. Ad esempio, {main,dev} viene attivato in caso di eventi push nei rami main e dev. Se il campo è vuoto o *, vengono segnalati gli eventi push per tutti i rami. Per informazioni sulla sintassi, consulta la documentazione relativa a glob.

  9. Fai clic su Aggiungi webhook.

  10. Il webhook viene visualizzato nella pagina Webhook.

REST

Per creare un webhook, richiama il metodo hooks.create inviando una richiesta POST all'endpoint hooks. Puoi autenticare il webhook utilizzando una stringa di query sensibile o l'autenticazione del account di servizio.

  • Sensitive query string

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
    "events": ["PUSH"]
    "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

    Il valore di SENSITIVE_QUERY_STRING_VALUE deve corrispondere a quello di key e secret nell'URL webhook. Ad esempio, se il tuo key è eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf e il tuo secret è MySecret, il tuo SENSITIVE_QUERY_STRING_VALUE dovrebbe essere key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret.

  • Autenticazione del service account

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook",
    "events": ["PUSH"],
    "serviceAccountAuth": true
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

Testare il webhook

  1. Nella pagina Webhook di Secure Source Manager, fai clic sul webhook che vuoi testare.

  2. Vai in fondo alla pagina e fai clic su Test di pubblicazione.

    Un evento segnaposto viene aggiunto alla coda di pubblicazione. Potrebbero essere necessari alcuni secondi prima che venga visualizzato nella cronologia delle consegne.

  3. Puoi anche utilizzare un comando git per fare il push o unire una richiesta di pull per testare il webhook.

  4. Controlla lo stato della build o dell'evento attivato nella cronologia build del servizio in cui hai configurato il trigger webhook.

  5. Puoi anche visualizzare la richiesta e la risposta alla consegna del test nella sezione Consegne recenti della pagina webhook di Secure Source Manager dopo aver inviato la prima consegna del test.

Sostituisci le variabili YAML di Cloud Build con i dati del payload

Se utilizzi webhook per connetterti a Cloud Build, puoi sostituire le variabili YAML di Cloud Build con i dati del payload del webhook di Secure Source Manager.

  1. Nella pagina Webhook di Secure Source Manager, nella sezione Recapiti recenti, fai clic sulla prima riga.

    Vengono visualizzati l'intestazione e i contenuti della richiesta inviati dal payload del webhook.

  2. Vai alla dashboard di Cloud Build, quindi fai clic su Trigger.

  3. Fai clic sull'attivatore che vuoi configurare.

  4. Nella sezione Avanzate, fai clic su + Aggiungi variabile nella sezione Variabili di sostituzione.

  5. Inserisci il nome e il valore della variabile. Il prefisso del valore è body.

    Ad esempio, per sostituire _REPO_URL con il campo dati del payload repository.clone_url e _COMMIT_SHA con l'ultimo SHA del commit in Cloud Build YAML, inserisci i seguenti nomi e valori:

    • Variabile 1: _REPO_URL Valore 1: $(body.repository.clone_url)
    • Variabile 2: _COMMIT_SHA Valore 2: $(body.after)

    Il file YAML di Cloud Build è simile al seguente:

    steps:
- name: gcr.io/cloud-builders/git
  env:
  - '_REPO_URL=$_REPO_URL'
  - '_COMMIT_SHA=$_COMMIT_SHA'
  script: |
    #!/bin/sh
    git clone ${_REPO_URL} /workspace
    cd /workspace
    git reset --hard ${_COMMIT_SHA}

Passaggi successivi