Se usó la API de Cloud Translation para traducir esta página.

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

Enable the Cloud Build, Secret Manager, and Compute Engine 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

Asegúrate de que el código fuente esté en un repositorio de Bitbucket Cloud.
Asegúrate de que el repositorio de código fuente de Bitbucket Cloud tenga un Dockerfile o un archivo de configuración de Cloud Build.
Instala Google Cloud CLI para usar los comandos de gcloud.

Permisos de IAM obligatorios

Para asegurarte de que tenga los permisos necesarios para conectarse, pídele a tu administrador que le otorgue a el rol de IAM de Administrador de conexiones de Cloud Build (cloudbuild.connectionAdmin) 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:

Accede a Bitbucket Cloud.
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
Nota: Algunos tipos de tokens solo están disponibles en Bitbucket Premium. Obtén más información sobre los tokens en Bitbucket Cloud.
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:

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

Abrir la página repositorios

Verás la página Repositorios.
En el selector de proyectos, selecciona tu proyecto de Google Cloud .
En la parte superior de la página, selecciona la pestaña 2ª gen..
Haz clic en Crear conexión de host para conectar un host nuevo a Cloud Build.
Selecciona Bitbucket como tu proveedor de fuentes.
En la sección Configurar conexión, ingresa la siguiente información:
1. Región: Selecciona una región para tu conexión.
  
  Nota: Debes especificar una región. Tu conexión no puede existir de forma global.
2. Nombre: Ingresa un nombre para tu conexión.
3. En la sección Detalles del host, selecciona Bitbucket Cloud como tu tipo de host.
4. Workspace: Ingresa el ID del espacio de trabajo de tu repositorio de Bitbucket Cloud.
5. Token de acceso: Ingresa el token de acceso de administrador que creaste anteriormente.
6. Token de acceso de lectura: Ingresa el token de acceso de lectura que creaste anteriormente.
Haz clic en Conectar.

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

gcloud

Para almacenar tus credenciales, completa los siguientes pasos:
1. Ejecuta los siguientes comandos para almacenar tus tokens de acceso en Secret Manager en tu proyectoGoogle Cloud :
```
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 quieres darle 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.
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 deseas 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 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 de Bitbucket Cloud antiguos o vencidos

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

Cuando intentas vincular un repositorio de Bitbucket Cloud a una 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:

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 Bitbucket Cloud 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, y authorizerCredential.userTokenSecretVersion muestra el nombre de Secret Manager del token Admin. Estos nombres se almacenan como secretos en Secret Manager.
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 el ID del token rotado.
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.
  
  Nota: Si no encuentras tu Secret en la ventana Secrets, selecciona la pestaña Regional Secrets y busca tu Secret en la ventana Regional Secrets.
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 Tokens de acceso y Mejora la seguridad en Bitbucket: Presentamos el vencimiento de los tokens de acceso en la documentación de Bitbucket Cloud.

¿Qué sigue?

Obtén más información para conectarte a un repositorio de Bitbucket Cloud.
Aprende a ver resultados de compilación.
Obtén información para realizar implementaciones azul-verde en Compute Engine.

Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.

Última actualización: 2026-01-06 (UTC)