Conéctate a un host de GitLab Enterprise Edition

En esta página, se explica cómo conectar el host de GitLab Enterprise Edition a Cloud Build.

Antes de comenzar

  • 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

Requisitos del host

  • Si no instalaste una instancia de servidor de GitLab Enterprise Edition, consulta la guía de instalación de GitLab Enterprise Edition para obtener instrucciones.

    Cuando sigas las instrucciones para instalar una instancia de GitLab Enterprise Edition Server, ten en cuenta lo siguiente:

    • Debes configurar tu host para que controle el protocolo HTTPS. No se admiten los hosts configurados con el protocolo HTTP.

    • Debes configurar tu host con la misma URL que se usa para acceder a él desde Google Cloud. Para obtener más información, consulta la documentación de GitLab para configurar la URL externa.

Permisos de IAM obligatorios

Para conectar tu host de GitLab Enterprise Edition, otorga la función de administrador de conexión de Cloud Build (roles/cloudbuild.connectionAdmin) a tu cuenta de usuario.

Para agregar los roles necesarios a tu cuenta de usuario, consulta Configura el acceso a los recursos de Cloud Build. Para obtener más información sobre los roles de IAM asociados con Cloud Build, consulta Roles y permisos de IAM.

Si tu instancia de GitLab Enterprise Edition está alojada en una red privada, consulta Compila repositorios desde GitLab Enterprise Edition en una red privada para obtener información sobre los roles de IAM adicionales que se requieren antes de la conexión del host.

Conéctate a un host de GitLab Enterprise Edition

Antes de crear una conexión de host para tu instancia de GitLab Enterprise Edition, debes crear tokens de acceso personal en GitLab Enterprise Edition. Para ello, completa los siguientes pasos:

  1. Accede a tu instancia de GitLab Enterprise Edition.

  2. En la página de GitLab Enterprise Edition de tu instancia, haz clic en tu avatar en la esquina superior derecha.

  3. Haz clic en Editar perfil.

  4. En la barra lateral izquierda, selecciona Tokens de acceso.

    Verás la página Tokens de acceso personal.

  5. Crea un token de acceso con el permiso api para conectar y desconectar repositorios.

  6. Crea un token de acceso con el alcance read_api para garantizar que los repositorios de Cloud Build puedan acceder al código fuente en los repositorios.

Console

Para conectar tu host de GitLab Enterprise Edition a Cloud Build, haz lo siguiente:

  1. Abre la página Repositorios en la consola de Google Cloud .

    Abrir la página repositorios

    Verás la página Repositorios.

  2. En la parte superior de la página, selecciona la pestaña 2ª gen..

  3. En el selector de proyectos de la barra superior, selecciona tu proyecto Google Cloud .

  4. Haz clic en Crear conexión de host para conectar un host nuevo a Cloud Build.

  5. En el panel izquierdo, selecciona GitLab como tu proveedor de fuentes.

  6. En la sección Configurar conexión, ingresa la siguiente información:

    1. Región: Selecciona una región para tu conexión.

    2. Nombre: Ingresa un nombre para tu conexión.

  7. En la sección Detalles del host, selecciona o ingresa la siguiente información:

    1. Proveedor de GitLab: Selecciona GitLab Enterprise Edition autoadministrado como tu proveedor.

    2. URL del host: Ingresa la URL del host para tu conexión. Por ejemplo, https://my-gle-server.net

    3. Certificado de CA: Haz clic en Examinar para subir tu certificado autofirmado.

    4. En Tipo de conexión, selecciona una de las siguientes opciones:

      1. Internet pública: Selecciona esta opción si se puede acceder a tu instancia a través de Internet pública.

      2. Acceso a la red privada: Selecciona esta opción si tu instancia está alojada en una red privada.

      3. En Servicio de directorio de servicios, selecciona la ubicación de tu servicio:

        • En el proyecto your-project
        • En otro proyecto
        • Ingresar manualmente

        1. Si seleccionas En otro proyecto o Ingresar manualmente, ingresa la siguiente información:

          • Project: Ingresa o selecciona tu ID de proyecto de Google Cloud en el menú desplegable.

          • Región: En este campo, se preselecciona la región de tu conexión. La región especificada para tu servicio debe coincidir con la región asociada a tu conexión.

        2. Espacio de nombres: Selecciona el espacio de nombres de tu servicio.

        3. Servicio: Selecciona el nombre del servicio en tu espacio de nombres.

  8. En la sección Tokens de acceso personal, ingresa la siguiente información:

    1. Token de acceso a la API: Ingresa el token con acceso al permiso api. Este token se usa para conectar y desconectar repositorios.

    2. Token de acceso a la API de lectura: Ingresa el token con acceso al permiso read_api. Los activadores de Cloud Build usan este token para acceder al código fuente en los repositorios.

  9. Haz clic en Conectar.

    Después de hacer clic en el botón Conectar, tus tokens de acceso personal se almacenarán de forma segura en Secret Manager. Después de la conexión del host, Cloud Build también crea un secreto de webhook en tu nombre. Puedes ver y administrar secretos en la página de Secret Manager. Puedes ver y administrar tus secretos en la página de Secret Manager.

Ya creaste correctamente una conexión de GitLab Enterprise Edition.

gcloud

Antes de conectar tu host de GitLab Enterprise Edition a Cloud Build, completa los siguientes pasos para almacenar tus credenciales:

  1. Almacena tu token en Secret Manager.

  2. Crea un secreto de webhook en Secret Manager ejecutando el siguiente comando:

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

  3. Si almacenas tus secretos en un proyecto Google Cloud diferente del que planeas usar para crear una conexión de host, ingresa el siguiente comando para otorgar acceso a tu proyecto al agente de servicio de 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"

    Aquí:

    • PROJECT_ID es el ID de tu proyecto de Google Cloud .

Ahora puedes conectar tu host de GitLab Enterprise Edition a Cloud Build.

Completa los siguientes pasos:

  1. Ingresa el siguiente comando para crear una conexión de 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

    Aquí:

    • CONNECTION_NAME es el nombre de tu conexión en Cloud Build.
    • HOST_URI es el URI de tu instancia de GitLab Enterprise Edition. Por ejemplo, https://my-gle-server.net
    • PROJECT_ID es el ID de tu proyecto de Google Cloud .
    • REGION es la región de tu conexión.
    • API_TOKEN es el nombre de tu token con el alcance de api.
    • READ_TOKEN es el nombre de tu token con el alcance de read_api.
    • SECRET_VERSION es la versión de tu secreto.
    • WEBHOOK_SECRET es tu secreto de webhook.

Ya creaste correctamente una conexión de GitLab Enterprise Edition.

Terraform

Puedes conectar tu host de GitLab Enterprise Edition a Cloud Build con Terraform. Obtén más información sobre Terraform en Google Cloud.

En el siguiente ejemplo, el fragmento de código hace lo siguiente:

  • Configura el proveedor de Terraform para los recursos de Google Cloud
  • Crea un secreto para almacenar tu token de acceso personal de GitLab Enterprise Edition
  • Otorga los permisos necesarios al agente de servicio de Cloud Build para acceder a los secretos.

  • Crea una conexión de 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
    ]
}

Reemplaza lo siguiente:

  • PROJECT_ID: El ID de tu proyecto Google Cloud .
  • GITLAB_PAT_API: Tu token de acceso personal con acceso a api.
  • GITLAB_API_TOKEN: Tu token de acceso personal.
  • GITLAB_PAT_READ: Tu token de acceso personal con acceso de read_api.
  • WEBHOOK_SECRET: Es el nombre del secreto que contiene el valor secreto de tu webhook.
  • WEBHOOK_SECRET_VALUE: Es el valor de tu secreto de webhook.

  • PROJECT_NUMBER: El número de tu proyecto Google Cloud . Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

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

  • REGION: Es la región de tu conexión.

  • CONNECTION_NAME: Es un nombre para la conexión del host de GitLab Enterprise Edition en Cloud Build.

  • URI: Es el URI de tu conexión, por ejemplo, https://my-gitlab-enterprise-server.net.

Ya creaste correctamente una conexión de GitLab Enterprise Edition.

Cómo rotar tokens de acceso antiguos o vencidos de GitLab Enterprise Edition

Si vence tu token de acceso de GitLab Enterprise Edition, se desconectará la conexión del host de Cloud Build de su repositorio de GitLab Enterprise Edition. Como resultado, verás errores en las siguientes circunstancias:

  • Cuando intentas vincular un repositorio de GitLab Enterprise Edition a la conexión de Cloud Build, aparece un mensaje de Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection.

  • En la página Activadores, cuando haces clic en Ejecutar, se abre la página Ejecutar activador y se muestra un mensaje de Failed to list branches. You can still enter one manually.

Para rotar un token antiguo o vencido para tu conexión, haz lo siguiente:

  1. Busca los secretos asociados con la conexión del host:

    1. Ejecuta el comando siguiente:

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      Aquí:

      • CONNECTION_PATH es la ruta de acceso de la conexión del host de GitLab Enterprise Edition en Cloud Build, con el formato projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME.
      • REGION es la región de tu conexión.

    2. En el resultado del comando, busca los valores de los campos de tu token de usuario. readAuthorizerCredential.userTokenSecretVersion muestra el nombre de Secret Manager del token read_api, y authorizerCredential.userTokenSecretVersion muestra el nombre de Secret Manager del token api. Estos nombres se almacenan como secretos en Secret Manager.

  2. Rota cada token de acceso en GitLab Enterprise Edition:

    1. Ve al repositorio de GitLab Enterprise Edition conectado a tu conexión de host de Cloud Build.

    2. Sigue las instrucciones de la documentación de GitLab para rotar un token de acceso. Cuando rotas un token, GitLab Enterprise Edition crea un token nuevo con credenciales nuevas y anula la versión anterior de ese token. El token rotado tiene los mismos permisos y alcance que el token original.

    3. Copia el ID del token rotado.

  3. Crea una nueva versión del secreto para cada token:

    1. Abre la página Secret Manager en la consola de Google Cloud :

      Abrir la página Administrador de secretos

    2. Para cada token que rotaste, busca el nombre del secreto que identificaste en el paso 1, haz clic en Acciones y, luego, en Agregar nueva versión.

    3. En la ventana Agregar versión nueva, ingresa el ID de tu token rotado y, luego, haz clic en Agregar versión nueva.

Para obtener más información, consulta Vencimiento del token de acceso en la documentación de GitLab Enterprise Edition.

¿Qué sigue?