Conéctate a un host de Bitbucket Cloud

En esta página, se explica cómo conectar un host de Bitbucket Cloud a Cloud Build.

Antes de comenzar

  • Habilita las APIs de Cloud Build, Secret Manager y Compute Engine si alguna aún no está habilitada.

    Roles necesarios para habilitar las APIs

    Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

Permisos de IAM obligatorios

Para asegurarte de que tenga los permisos necesarios para conectarse, pídele a tu administrador que le otorgue el rol de IAM de administrador de conexiones de Cloud Build (cloudbuild.connectionAdmin) a en tu cuenta de usuario. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Crea tokens de acceso de Bitbucket Cloud

Crea los siguientes dos tokens de acceso en Bitbucket Cloud:

  • Token de acceso de administrador: Se usa para conectar y desconectar repositorios.
  • Token de acceso de lectura: Para permitir que Cloud Build acceda a tu código fuente.

Para crear estos tokens, sigue estos pasos:

  1. Accede a Bitbucket Cloud.

  2. Sigue las instrucciones de Bitbucket Cloud para crear tokens de acceso vinculados a tu repositorio, proyecto o espacio de trabajo.

    Otorga los siguientes permisos:

    • Token de acceso de administrador:

      • Repositorios: Lectura y Administrador
      • Pull Requests: Read
      • Webhooks: Lectura y Escritura

    • Token de acceso de lectura:

      • Repositorios: Lectura

  3. Copia tus tokens para usarlos en los siguientes procedimientos.

Conéctate a un host de Bitbucket Cloud

Console

Para conectar Cloud Build a tu host de Bitbucket Cloud, 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 el selector de proyectos, 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 Bitbucket como tu proveedor de origen.

  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. En la sección Detalles del host, ingresa la siguiente información:

    • Selecciona Bitbucket Cloud como tu tipo de host.

    • Espacio de trabajo: Ingresa el ID del espacio de trabajo de tu repositorio de Bitbucket Cloud.

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

  9. En la sección Tokens de acceso, ingresa lo siguiente:

  10. Haz clic en Conectar.

    La conexión nueva aparecerá en la página Repositorios.

gcloud

  1. Para almacenar tus credenciales, completa los siguientes pasos:

    1. Almacena tus tokens de acceso en Secret Manager en tu proyectoGoogle Cloud ejecutando los siguientes comandos:

      echo -n ADMIN_TOKEN | gcloud secrets create ADMIN_SECRET_NAME --data-file=-

echo -n READ_TOKEN | gcloud secrets create READ_SECRET_NAME --data-file=-

      Aquí:

      • ADMIN_TOKEN es tu token de acceso de administrador.
      • ADMIN_SECRET_NAME es el nombre que deseas asignarle a tu secreto de token de acceso de administrador en Secret Manager.
      • READ_TOKEN es tu token de acceso de lectura.
      • READ_SECRET_NAME es el nombre que deseas asignar a tu secreto de token de acceso de lectura en Secret Manager.

    2. Crea un secreto de webhook en Secret Manager ejecutando el siguiente comando, en el que WEBHOOK_SECRET_NAME es el nombre que deseas asignarle a tu secreto de webhook:

      echo -n ${ex.(random-uuid)} | gcloud secrets create WEBHOOK_SECRET_NAME --data-file=-

    3. Si tus secretos no están todos en el mismo proyecto, otorga acceso a tu agente de servicio de Cloud Build ejecutando el siguiente comando:

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

gcloud secrets add-iam-policy-binding READ_SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_ACCOUNT}" \
    --role="roles/secretmanager.secretAccessor"

gcloud secrets add-iam-policy-binding WEBHOOK_SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_ACCOUNT}" \
    --role="roles/secretmanager.secretAccessor"

      Aquí:

      • PROJECT_ID es el Google Cloud ID del proyecto.
      • ADMIN_SECRET_NAME es el nombre de tu secreto de token de administrador.
      • READ_SECRET_NAME es el nombre de tu secreto de token de lectura.
      • WEBHOOK_SECRET_NAME es el nombre de tu secreto de webhook.

  2. Conecta Cloud Build a tu host de Bitbucket Cloud con el siguiente comando:

    gcloud builds connections create bitbucket-cloud CONNECTION_NAME \
    --workspace=WORKSPACE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/ADMIN_SECRET_NAME/versions/latest \
    --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_SECRET_NAME/versions/latest \
    --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET_NAME/versions/1

    Aquí:

    • CONNECTION_NAME es el nombre que quieres asignar a la conexión con tu host de Bitbucket Cloud.
    • WORKSPACE_ID es el ID del espacio de trabajo de tu repositorio de Bitbucket Cloud.
    • PROJECT_ID es el Google Cloud ID del proyecto.
    • REGION es la región de la conexión del host.
    • ADMIN_SECRET_NAME es el nombre de tu secreto de token de administrador.
    • READ_SECRET_NAME es el nombre de tu secreto del token de acceso de lectura.
    • WEBHOOK_SECRET_NAME es el nombre de tu secreto de webhook.

Terraform

Puedes conectar tu host de Bitbucket Cloud a Cloud Build con Terraform.

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

  • Configura el proveedor de Google de Terraform.
  • Crea un secreto de Secret Manager para almacenar los tokens de Bitbucket.
  • Otorga los permisos necesarios al agente de servicio de Cloud Build para acceder a los secretos.

  • Crea una conexión de Bitbucket Cloud.

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

provider "google" {
  project = "PROJECT_ID"
  region = "REGION"
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "admin-token-secret" {
    project = "PROJECT_ID"
    secret_id = "ADMIN_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "admin-token-secret-version" {
    secret = google_secret_manager_secret.admin-token-secret.id
    secret_data = "ADMIN_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "read-token-secret" {
    project = "PROJECT_ID"
    secret_id = "READ_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "read-token-secret-version" {
    secret = google_secret_manager_secret.read-token-secret.id
    secret_data = "READ_TOKEN_VALUE"
}

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

    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" "p4sa-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.admin-token-secret.project
  secret_id = google_secret_manager_secret.admin-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-token-secret.project
  secret_id = google_secret_manager_secret.read-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-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.p4sa-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"

    bitbucket_cloud_config {
        workspace = "WORKSPACE_ID"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.admin-token-secret-version.id
        }
        read_authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.read-token-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
    ]
}

Aquí:

  • PROJECT_ID es el Google Cloud ID del proyecto.
  • PROJECT_NUMBER es el número de tu proyecto de Google Cloud .
  • ADMIN_TOKEN_NAME es el nombre de tu token con acceso de alcance a webhook, repository, repository:admin y pullrequest.
  • ADMIN_TOKEN_VALUE es el valor de tu ADMIN_TOKEN_NAME.
  • READ_TOKEN_NAME es el nombre de tu token con alcance de repository:read.
  • READ_TOKEN_VALUE es el valor de tu READ_TOKEN_NAME.
  • WEBHOOK_SECRET_NAME es el nombre de tu secreto de webhook.
  • WEBHOOK_SECRET_VALUE es el valor de tu WEBHOOK_SECRET_NAME.
  • REGION es la región de tu conexión.
  • CONNECTION_NAME es el nombre de tu conexión.
  • WORKSPACE_ID es el ID del espacio de trabajo de tu repositorio de Bitbucket Cloud.

Cómo rotar tokens de acceso antiguos o vencidos de Bitbucket Cloud

Rota tus tokens de acceso para que la conexión del host de Cloud Build pueda mantener su conexión con tu repositorio de Bitbucket Cloud. Si vence tu token de acceso a Bitbucket Cloud, se desconectará la conexión del host de Cloud Build de su repositorio de Bitbucket Cloud. Cuando esto sucede, no puedes inhabilitar la conexión ni vincular un repositorio hasta que rotes el token vencido. Además, verás errores en las siguientes circunstancias:

  • En la página Detalles de la conexión de tu conexión, se muestra un mensaje de error que indica Connection is disconnected due to an invalid or expired access token.

  • Si intentas vincular un repositorio a una conexión que tiene un token de acceso vencido, verás el mensaje Invalid access token. Si haces clic en Ver conexión, se te redireccionará a la página Detalles de la conexión de la conexión con el token vencido.

Cloud Build te permite rotar los tokens de acceso ingresando valores de tokens nuevos y guardándolos en Secret Manager en la versión más reciente del secreto para esos tokens. Para rotar tus tokens de acceso, haz lo siguiente:

  1. Rota cada token de acceso en Bitbucket Cloud:

    1. Ve al repositorio de Bitbucket Cloud conectado a tu conexión de host de Cloud Build.

    2. Sigue las instrucciones de la documentación de Bitbucket para rotar un token de acceso. Cuando rotas un token, Bitbucket Cloud crea uno 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 los IDs de los tokens rotados.

  2. Actualiza tu token de acceso en Cloud Build:

    1. Ve a la página Detalles de la conexión de tu conexión.

    2. Selecciona Actualizar tokens de acceso.

    3. En el menú Rotación de tokens, ingresa tus tokens nuevos en los campos Token de acceso a la API y Token de acceso de lectura.

    4. Opcional: Si quieres que tu conexión siempre use la versión más reciente del secreto para tus tokens, selecciona Actualizar la conexión para usar siempre la versión más reciente. Dejar esta opción sin seleccionar puede ser útil si tu conexión usa un número de versión secreto específico.

    5. Selecciona Actualizar para guardar los cambios.

      Cloud Build guarda los tokens de acceso nuevos como la versión más reciente de tu secreto en Secret Manager.

Para obtener más información, consulta Tokens de acceso y Mejora la seguridad en Bitbucket: Presentamos la fecha de vencimiento para los tokens de acceso en la documentación de Bitbucket Cloud.

¿Qué sigue?