Connettiti a un host GitLab Enterprise Edition

Questa pagina spiega come connettersi all'host GitLab Enterprise Edition a Cloud Build.

Prima di iniziare

  • Enable the Cloud Build and Secret Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Requisiti dell'host

  • Se non hai installato un'istanza del server GitLab Enterprise Edition, consulta la guida all'installazione di GitLab Enterprise Edition per istruzioni.

    Quando segui le istruzioni per installare un'istanza di GitLab Enterprise Edition Server, tieni presente quanto segue:

    • Devi configurare l'host per gestire il protocollo HTTPS. Gli host configurati con il protocollo HTTP non sono supportati.

    • Devi configurare l'host con lo stesso URL utilizzato per raggiungere l'host da Google Cloud. Per saperne di più, consulta la documentazione di GitLab sulla configurazione dell'URL esterno.

Autorizzazioni IAM obbligatorie

Per connettere l'host GitLab Enterprise Edition, concedi il ruolo Amministratore connessioni Cloud Build (roles/cloudbuild.connectionAdmin) al tuo account utente.

Per aggiungere i ruoli richiesti al tuo account utente, consulta Configurazione dell'accesso alle risorse Cloud Build. Per scoprire di più sui ruoli IAM associati a Cloud Build, consulta Ruoli e autorizzazioni IAM.

Se la tua istanza di GitLab Enterprise Edition è ospitata in una rete privata, consulta Creare repository da GitLab Enterprise Edition in una rete privata per scoprire di più sui ruoli IAM aggiuntivi richiesti prima della connessione host.

Connettiti a un host GitLab Enterprise Edition

Prima di creare una connessione all'host per l'istanza GitLab Enterprise Edition, devi creare token di accesso personale in GitLab Enterprise Edition completando i seguenti passaggi:

  1. Accedi all'istanza GitLab Enterprise Edition.

  2. Nella pagina GitLab Enterprise Edition della tua istanza, fai clic sul tuo avatar nell'angolo in alto a destra.

  3. Fai clic su Modifica profilo.

  4. Nella barra laterale sinistra, seleziona Token di accesso.

    Viene visualizzata la pagina Token di accesso personali.

  5. Crea un token di accesso con l'ambito api da utilizzare per collegare e scollegare i repository.

  6. Crea un token di accesso con l'ambito read_api per garantire che i repository Cloud Build possano accedere al codice sorgente nei repository.

Console

Per connettere l'host GitLab Enterprise Edition a Cloud Build:

  1. Apri la pagina Repository nella console Google Cloud .

    Apri la pagina Repository

    Viene visualizzata la pagina Repository.

  2. Nella parte superiore della pagina, seleziona la scheda 2ª gen..

  3. Nel selettore di progetti nella barra superiore, seleziona il tuo progetto Google Cloud .

  4. Fai clic su Crea connessione host per connettere un nuovo host a Cloud Build.

  5. Nel riquadro a sinistra, seleziona GitLab come provider di origine.

  6. Nella sezione Configura connessione, inserisci le seguenti informazioni:

    1. Regione: seleziona una regione per la connessione.

    2. Name (Nome): inserisci un nome per la connessione.

  7. Nella sezione Dettagli host, seleziona o inserisci le seguenti informazioni:

    1. Provider GitLab: seleziona GitLab Enterprise Edition autogestito come provider.

    2. URL host: inserisci l'URL host per la connessione. Ad esempio, https://my-gle-server.net.

    3. Certificato CA: fai clic su Sfoglia per caricare il certificato autofirmato.

    4. In Tipo di connessione, seleziona una delle seguenti opzioni:

      1. Internet pubblico: seleziona questa opzione se la tua istanza è accessibile tramite internet pubblico.

      2. Accesso alla rete privata: seleziona questa opzione se la tua istanza è ospitata in una rete privata.

      3. Nella sezione Servizio Service Directory, seleziona la località per il tuo servizio:

        • Nel progetto your-project
        • In un altro progetto
        • Inserisci manualmente

        1. Se selezioni In un altro progetto o Inserisci manualmente, inserisci le seguenti informazioni:

          • Progetto: inserisci o seleziona l'ID progetto Google Cloud dal menu a discesa.

          • Regione: questo campo pre-seleziona la regione della connessione. La regione specificata per il tuo servizio deve corrispondere alla regione associata alla tua connessione.

        2. Spazio dei nomi: seleziona lo spazio dei nomi del tuo servizio.

        3. Servizio: seleziona il nome del servizio nel tuo spazio dei nomi.

  8. Nella sezione Personal access tokens (Token di accesso personale), inserisci le seguenti informazioni:

    1. Token di accesso API: inserisci il token con accesso all'ambito api. Questo token viene utilizzato per collegare e scollegare i repository.

    2. Token di accesso alle API in lettura: inserisci il token con accesso all'ambito read_api. I trigger di Cloud Build utilizzano questo token per accedere al codice sorgente nei repository.

  9. Fai clic su Connetti.

    Dopo aver fatto clic sul pulsante Connetti, i tuoi token di accesso personali vengono archiviati in modo sicuro in Secret Manager. Dopo la connessione host, Cloud Build crea anche un secret webhook per tuo conto. Puoi visualizzare e gestire i secret nella pagina Secret Manager. Puoi visualizzare e gestire i tuoi secret nella pagina Secret Manager.

Ora hai creato correttamente una connessione GitLab Enterprise Edition.

gcloud

Prima di connettere l'host GitLab Enterprise Edition a Cloud Build, completa i seguenti passaggi per archiviare le credenziali:

  1. Archivia il token in Secret Manager.

  2. Crea un secret webhook in Secret Manager eseguendo il seguente comando:

     cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-

  3. Se memorizzi i tuoi secret in un progetto Google Cloud diverso da quello che prevedi di utilizzare per creare una connessione host, inserisci il seguente comando per concedere al tuo progetto l'accesso all'agente di servizio Cloud Build:

    PN=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT} \
  --role="roles/secretmanager.admin"

    Dove:

    • PROJECT_ID è l'ID progetto Google Cloud .

Ora puoi procedere per connettere l'host GitLab Enterprise Edition a Cloud Build.

Completa i seguenti passaggi:

  1. Inserisci il comando seguente per creare una connessione GitLab Enterprise Edition:

    gcloud builds connections create gitlab CONNECTION_NAME \
  --host-uri=HOST_URI \
  --project=PROJECT_ID \
  --region=REGION \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/API_TOKEN/versions/SECRET_VERSION \
  --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION

    Dove:

    • CONNECTION_NAME è un nome per la connessione in Cloud Build.
    • HOST_URI è l'URI della tua istanza GitLab Enterprise Edition. Ad esempio, https://my-gle-server.net.
    • PROJECT_ID è l'ID progetto Google Cloud .
    • REGION è la regione per la tua connessione.
    • API_TOKEN è il nome del tuo token con ambito api.
    • READ_TOKEN è il nome del tuo token con ambito read_api.
    • SECRET_VERSION è la versione del secret.
    • WEBHOOK_SECRET è il secret webhook.

Ora hai creato correttamente una connessione GitLab Enterprise Edition.

Terraform

Puoi connettere il tuo host GitLab Enterprise Edition a Cloud Build utilizzando Terraform. Scopri di più su Terraform su Google Cloud.

Nel seguente esempio, lo snippet di codice esegue queste operazioni:

  • Configura le risorse del provider Terraform per Google Cloud
  • Crea un secret per archiviare il token di accesso personale di GitLab Enterprise Edition
  • Concede le autorizzazioni necessarie al service agent Cloud Build per accedere ai secret

  • Crea una connessione GitLab Enterprise Edition

    // Configure the Terraform Google provider
terraform {
  required_providers {
    google = {}
  }
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "api-pat-secret" {
    project = "PROJECT_ID"
    secret_id = "GITLAB_PAT_API"

    replication {
        auto {}
     }
 }

 resource "google_secret_manager_secret_version" "api-pat-secret-version" {
     secret = google_secret_manager_secret.api-pat-secret.id
     secret_data = "GITLAB_API_TOKEN"
 }

 resource "google_secret_manager_secret" "read-pat-secret" {
     project = "PROJECT_ID"
     secret_id = "GITLAB_PAT_READ"

     replication {
         auto {}
     }
}

resource "google_secret_manager_secret_version" "read-pat-secret-version" {
    secret = google_secret_manager_secret.read-pat-secret.id
    secret_data = "GITLAB_API_TOKEN"
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

data "google_iam_policy" "serviceagent-secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy-pak" {
  project = google_secret_manager_secret.api-pat-secret.project
  secret_id = google_secret_manager_secret.api-pat-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-pat-secret.project
  secret_id = google_secret_manager_secret.read-pat-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
}

// Create the connection and add the repository resource
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    gitlab_config {
        host_uri = "URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.api-pat-secret-version.id
        }
        read_authorizer_credential {
             user_token_secret_version = google_secret_manager_secret_version.read-pat-secret-version.id
        }
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pak,
        google_secret_manager_secret_iam_policy.policy-rpak,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • GITLAB_PAT_API: il tuo token di accesso personale con accesso api.
  • GITLAB_API_TOKEN: il tuo token di accesso personale.
  • GITLAB_PAT_READ: il tuo token di accesso personale con accesso read_api.
  • WEBHOOK_SECRET: il nome del secret contenente il valore del secret webhook.
  • WEBHOOK_SECRET_VALUE: il valore del secret del webhook.

  • PROJECT_NUMBER: il tuo Google Cloud numero di progetto. Puoi trovare il numero di progetto nella pagina Benvenuto della console Google Cloud o eseguendo questo comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  • REGION: la regione per la connessione.

  • CONNECTION_NAME: un nome per la connessione host GitLab Enterprise Edition in Cloud Build.

  • URI: l'URI della connessione, ad esempio https://my-gitlab-enterprise-server.net.

Ora hai creato correttamente una connessione GitLab Enterprise Edition.

Ruotare i token di accesso GitLab Enterprise Edition vecchi o scaduti

Se il token di accesso GitLab Enterprise Edition scade, la connessione dell'host Cloud Build viene disconnessa dal repository GitLab Enterprise Edition. Di conseguenza, visualizzerai errori nelle seguenti circostanze:

  • Quando provi a collegare una connessione Cloud Build a un repository GitLab Enterprise Edition, viene visualizzato un messaggio Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection.

  • Nella pagina Trigger, quando fai clic su Esegui, si apre la pagina Esegui trigger e viene visualizzato un messaggio Failed to list branches. You can still enter one manually.

Per ruotare un token precedente o scaduto per la connessione:

  1. Trova i segreti associati alla connessione host:

    1. Esegui questo comando:

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      Dove:

      • CONNECTION_PATH è il percorso della connessione all'host GitLab Enterprise Edition in Cloud Build, nel formato projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME.
      • REGION è la regione per la tua connessione.

    2. Nell'output del comando, cerca i valori dei campi del token utente. readAuthorizerCredential.userTokenSecretVersion mostra il nome di Secret Manager del token read_api e authorizerCredential.userTokenSecretVersion mostra il nome di Secret Manager del token api. Questi nomi vengono archiviati come secret in Secret Manager.

  2. Ruota ogni token di accesso in GitLab Enterprise Edition:

    1. Vai al repository GitLab Enterprise Edition connesso alla connessione all'host Cloud Build.

    2. Segui le istruzioni riportate nella documentazione di GitLab per ruotare un token di accesso. Quando ruoti un token, GitLab Enterprise Edition ne crea uno nuovo con nuove credenziali e invalida la versione precedente. Il token ruotato ha le stesse autorizzazioni e lo stesso ambito del token originale.

    3. Copia l'ID del token ruotato.

  3. Crea una nuova versione del secret per ogni token:

    1. Apri la pagina Secret Manager nella console Google Cloud :

      Apri la pagina Secret Manager

    2. Per ogni token che hai ruotato, trova il nome del secret che hai identificato nel passaggio 1 e fai clic su Azioni, quindi fai clic su Aggiungi nuova versione.

    3. Nella finestra Aggiungi nuova versione, inserisci l'ID del token ruotato e poi fai clic su Aggiungi nuova versione.

Per maggiori informazioni, consulta la sezione Scadenza del token di accesso nella documentazione di GitLab Enterprise Edition.

Passaggi successivi