Conéctate a un repositorio de GitHub

En esta página, se explica cómo conectar un repositorio de GitHub a Cloud Build. Para obtener más información sobre los repositorios de Cloud Build, consulta Repositorios de Cloud Build.

Antes de comenzar

  • Habilita las APIs de Cloud Build y Secret Manager.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

  • Ten listo tu código fuente en un repositorio de GitHub.
  • Tener un Dockerfile o un archivo de configuración de Cloud Build en tu repositorio de código fuente de GitHub
  • Si es la primera vez que conectas tu repositorio a Cloud Build, asegúrate de tener permisos de administrador en él. Para obtener más información sobre los permisos de los repositorios de GitHub, consulta Niveles de permisos de repositorios para una organización.

  • Para usar los comandos de gcloud en esta página, instala Google Cloud CLI.

Conéctate a un host de GitHub

Console

Para conectar tu repositorio de GitHub a Cloud Build:

  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 el selector de proyectos de la barra superior, selecciona tu proyecto de Google Cloud .

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

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

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

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

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

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

  7. Opcional: Si deseas administrar las claves de encriptación que se usan para encriptar los tokens de acceso de tus repositorios de GitHub, ve a la sección Encriptación y elige una clave de Cloud Key Management Service. Para obtener más información, consulta Cómo habilitar claves de encriptación administradas por el cliente para Secret Manager.

  8. Haz clic en Conectar.

    Después de hacer clic en el botón Conectar, se te pedirá que autorices a la app de GitHub de Cloud Build para que acceda a tu cuenta de GitHub. Puedes revocar el acceso a la app desinstalándola o borrándola de tu host en cualquier momento.

    Cloud Build solicita la autorización de tu cuenta de usuario de GitHub y almacena el token de autorización resultante como un secreto en Secret Manager en tu proyecto. El token de autorización se usa para validar el acceso de tu cuenta de usuario a la instalación de la app de Cloud Build en GitHub y a los repositorios vinculados. La cuenta del agente de servicio de Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) se usa para acceder a tu secreto. Para ver tu secreto, consulta Enumera secretos y visualiza detalles de secretos.

    Después de autorizar la app de GitHub de Cloud Build, se te redireccionará a la página Repositorios de Cloud Build.

gcloud

Para conectar tu host de GitHub con gcloud, completa los siguientes pasos:

  1. Ingresa el siguiente comando para iniciar una conexión a tu repositorio de GitHub:

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    Aquí:

    • CONNECTION_NAME es el nombre de tu conexión, tal como aparecerá en Cloud Build.

    • REGION es la región del activador.

    Después de ejecutar el comando gcloud builds connections, verás un vínculo para autorizar la app de GitHub de Cloud Build.

  2. Accede a tu cuenta de github.com.

  3. Sigue el vínculo para autorizar la app de GitHub de Cloud Build.

    Después de autorizar la app, Cloud Build almacena un token de autenticación como un secreto en Secret Manager en tu proyecto Google Cloud. Puedes ver tus secretos en la página de Secret Manager.

  4. Instala la app de GitHub de Cloud Build en tu cuenta o en una cuenta de organización que poseas.

    Permite la instalación con tu cuenta de GitHub y selecciona los permisos del repositorio cuando se te solicite.

  5. Para verificar la instalación de tu conexión de GitHub, ejecuta el siguiente comando:

     gcloud builds connections describe CONNECTION_NAME --region=REGION

    Aquí:

    • CONNECTION_NAME es el nombre de tu conexión de host de GitHub en Cloud Build.
    • REGION es la región del activador.

    Si el campo installationState está establecido en COMPLETE, instalaste correctamente la conexión. De lo contrario, el campo installationState proporciona un vínculo para los pasos adicionales requeridos.

Conéctate a un host de GitHub de manera programática

Para conectarte a un host de GitHub de forma programática, primero debes configurar el token de autenticación para la conexión y, luego, crear la conexión de GitHub en Cloud Build.

Configura un token de autenticación

Para conectarte a un host de GitHub de manera programática, debes crear una conexión de GitHub de Cloud Build, que incluye un secreto para un token de autenticación. Puedes adquirir un token de autenticación de dos maneras:

  • Crea un token de acceso personal en GitHub.

  • Usa un token de una conexión existente de Cloud Build a GitHub. Este método es útil si tu cuenta de GitHub tiene restricciones que impiden la creación de tokens de acceso personal. Además, si haces referencia a este token cuando creas una conexión desde una secuencia de comandos, no es necesario que autentiques la conexión de forma manual con un navegador web.

Token de acceso personal

  1. Sigue los pasos para crear un token de acceso personal en la documentación de GitHub.

  2. Selecciona los siguientes permisos de OAuth cuando se te solicite en GitHub:

    • repo para otorgar acceso completo a repositorios públicos y privados
    • read:user para otorgar acceso a la lectura de los datos del perfil de un usuario
    • read:org para el acceso de solo lectura a la membresía de la organización y los proyectos (si tu app está instalada en una organización)

  3. Guarda el valor de tu token de acceso personal. y la usará más adelante en otro paso.

Conexión existente

  1. Ejecuta el siguiente comando en gcloud CLI:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Aquí:

    • CONNECTION_NAME es el nombre de tu conexión de host de GitHub.
    • REGION es la región del activador.

  2. En el resultado del comando, el valor de authorizerTokenSecretVersion es el ID del secreto que contiene el token de autenticación de la conexión. Copia este valor y guárdalo en un lugar seguro. Usarás el token generado en los siguientes pasos.

Crea la conexión de GitHub

Crea una conexión a GitHub con Terraform o gcloud CLI.

Terraform

Puedes conectar tu host de GitHub a Cloud Build con el proveedor de Google Terraform. Para ello, completa los siguientes pasos:

  1. Instala la app de GitHub de Cloud Build en tu cuenta de GitHub o en una organización que poseas.

  2. Configura tu conexión de GitHub en Terraform. En la siguiente muestra de código de Terraform, se muestra una configuración que hace lo siguiente:

    • Configura el proveedor de Google de Terraform

    • Crea un secreto para almacenar tokens de acceso personal de GitHub

    • Otorga permisos al agente de servicio de Cloud Build para acceder al secreto

    • Crea una conexión de GitHub

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

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

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" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

Aquí:

  • PROJECT_NUMBER es tu número de proyecto de Google Cloud .
  • SECRET_ID es el ID de tu token de acceso personal o secreto de GitHub en Secret Manager.
  • GITHUB_PAT es el token de acceso del token de acceso personal en GitHub.
  • PROJECT_ID es el ID de tu proyecto de Google Cloud .
  • REGION es la región de tu conexión.
  • CONNECTION_NAME es el nombre de tu conexión, tal como aparecerá en Cloud Build.
  • INSTALLATION_ID es el ID de instalación de tu app de GitHub de Cloud Build. Puedes encontrarlo en la URL de la app de GitHub de Cloud Build. En la siguiente URL, https://github.com/settings/installations/1234567, el ID de instalación es el valor numérico 1234567.

gcloud

Para conectar tu host de GitHub a Cloud Build, haz lo siguiente:

  1. Instala la app de GitHub de Cloud Build en tu cuenta de GitHub o en una organización que poseas.

  2. Es opcional. Si usas un token de acceso personal de GitHub para la autenticación, ejecuta el siguiente comando para almacenar el token en Secret Manager en tu proyecto Google Cloud :

    echo -n 'TOKEN' | gcloud secrets create SECRET_NAME --data-file=-

  3. Otorga acceso al agente de servicio de Cloud Build en el secreto, donde SECRET_NAME es el nombre de tu secreto tal como se almacena en Secret Manager:

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

  4. Crea tu conexión de GitHub:

    gcloud builds connections create github CONNECTION_NAME \
  --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION  \
  --app-installation-id=INSTALLATION_ID --region=REGION

    Aquí:

    • CONNECTION_NAME es el nombre de tu conexión de host de GitHub en Cloud Build.
    • PROJECT_ID es el ID de tu proyecto de Google Cloud .
    • SECRET_NAME es el nombre de tu secreto almacenado en Secret Manager.
    • VERSION es la versión de tu secreto.
    • INSTALLATION_ID es el ID de instalación de tu app de GitHub. Puedes encontrarlo en la URL de tu app de GitHub de Cloud Build. En la siguiente URL, https://github.com/settings/installations/1234567, el ID de instalación es el valor numérico 1234567.
    • REGION es la región de tu conexión.

Conecta un repositorio de GitHub

Console

Para conectar un repositorio de GitHub a una conexión con el host, completa los siguientes pasos:

  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. Haz clic en Vincular repositorios para vincular repositorios desde tu conexión.

    Verás el panel Conectar repositorios.

  4. En el panel Connect Repositories, ingresa la siguiente información:

    1. Conexión: Selecciona una conexión en el menú desplegable.

    2. Repositorio: Selecciona un repositorio para vincularlo a tu conexión.

    3. Nombre del repositorio: Ingresa un nombre para tu repositorio.

      1. Generados: Selecciona esta opción para que Cloud Build genere automáticamente nombres de repositorios en tu nombre para los repositorios seleccionados.

      2. Manual: Selecciona esta opción para especificar manualmente los nombres de los repositorios seleccionados.

        Si seleccionas Manual, puedes modificar los nombres de los repositorios seleccionados en la sección Nombres de repositorios.

  5. Haz clic en Vincular para vincular tu repositorio a la conexión.

gcloud

Para agregar un repositorio de GitHub a tu conexión, ingresa el siguiente comando:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

Aquí:

  • REPO_NAME es el nombre del repositorio.
  • REPO_URI es el vínculo a tu repositorio de GitHub. Por ejemplo, https://github.com/cloud-build/test-repo.git.
  • CONNECTION_NAME es el nombre que se le asignó a la conexión de host de GitHub Enterprise creada en Cloud Build desde Connect to a GitHub host.
  • REGION es la región de tu conexión.

Terraform

Para agregar un repositorio de GitHub a tu conexión, agrega el siguiente fragmento de código a tu configuración de Terraform:

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

Aquí:

  • PROJECT_ID es el ID de tu proyecto de Google Cloud .
  • REPO_NAME es el nombre de tu repositorio de GitHub.
  • REGION es la región de tu conexión.
  • URI es el URI del host de tu repositorio. Por ejemplo, https://github.com/myuser/myrepo.git.

¿Qué sigue?