Conéctate a un host de Bitbucket Server

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

Antes de comenzar

Habilita las API de Cloud Build, Secret Manager, and Compute Engine.
Habilita las API

Si no instalaste una instancia de Bitbucket Server, consulta la Guía de instalación de Bitbucket Server para obtener instrucciones.

Establece la configuración

Antes de conectar el host de Bitbucket Server, debes obtener una clave de API para autenticar y aceptar eventos entrantes de Bitbucket Server. Además, debes otorgar permisos de IAM en tu proyecto de Google Cloud a fin de crear tokens de acceso personal en Bitbucket Server para crear webhooks y recuperar datos de repositorio.

Obtén una clave de API

Para conectar tu host y autenticar eventos de webhook entrantes, necesitas una clave de API.

Para obtener una clave de API, haz lo siguiente:

Abre la página Credenciales en la consola de Google Cloud:

Abre la página Credenciales.
Haz clic en Crear credenciales.
Haz clic en Clave de API.

Verás un diálogo con la clave de API creada. Toma nota de tu clave de API.
Si deseas restringir tu clave para las aplicaciones de productos, haz clic en Restringir clave a fin de completar los pasos adicionales para protegerla. De lo contrario, haz clic en Cerrar.

Si deseas obtener información para restringir tu clave, consulta Aplica restricciones de clave de API.

Permisos de IAM obligatorios

Para conectar el host de Bitbucket Server, otorga la función de editor de Cloud Build (roles/cloudbuild.builds.editor) y la función de propietario de integraciones de Cloud Build (cloudbuild.integrations.owner) 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 las funciones de IAM asociadas con Cloud Build, consulta Funciones y permisos de IAM.

Crea tokens de acceso personal

Debes crear dos tokens de acceso personal en Bitbucket Server para realizar las siguientes tareas:

Crea webhooks: Crea un token de acceso personal con acceso de admin.
Recupera datos del repositorio: crea un token de acceso personal con acceso de lectura. De manera opcional, puedes crear un token que tenga acceso de lectura y escritura.

Estos tokens de acceso personal son los permisos mínimos obligatorios. Es posible que debas configurar permisos adicionales en el servidor de Bitbucket según sea necesario. Por ejemplo, puedes seleccionar Cuenta de servidor de Bitbucket para tener acceso solo a un subconjunto de repositorios en tu instancia de Bitbucket Server a fin de tener un control más preciso de lo que está disponible en Cloud Build.

Después de crear tus tokens de acceso personales, guarda los valores de estos de forma segura para conectarte a tu repositorio de Bitbucket Server.

Conéctate a un host de Bitbucket Server

Consola

Para conectar el host de Bitbucket Server a Cloud Build con la consola de Google Cloud, sigue estos pasos:

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

Abrir la página repositorios
En la parte superior de la página, selecciona la pestaña 1a gen..
Haz clic en Conectar host.
Selecciona Servidor de Bitbucket en el menú desplegable.

Verás el panel Conectar host.

Ingresa la siguiente información para conectar tu instancia de Bitbucket Server a Cloud Build:
- Región: Selecciona la región de tu conexión.
- Nombre: Ingresa un nombre para la conexión.
1. URL del host: la URL del host de tu instancia de Bitbucket Server. Por ejemplo, https://bbs.example-test.com:7990
2. Clave de API de Google Cloud: La clave de API que se usa para autenticar tus credenciales.
3. Certificado de CA: Tu certificado autofirmado. El certificado no debe superar los 10 KB de tamaño y debe estar en formato PEM (.pem, .cer o .crt). Si esta sección se deja en blanco, se utiliza un conjunto predeterminado de certificados.
4. Nombre de usuario: El nombre de usuario de tu cuenta de Bitbucket Server. Esta cuenta debe tener acceso de administrador a los repositorios que deseas conectar con Cloud Build.
5. Token de acceso de lectura: El token de acceso personal de tu cuenta de Bitbucket Server con permisos de lectura.
6. Token de acceso de administrador: El token de acceso personal de tu cuenta de Bitbucket Server con permisos de administrador en proyectos y repositorios.
7. En Tipo de red, 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 la Internet pública.
  2. Red privada: Selecciona esta opción si tu instancia está alojada en una red privada.
    1. Project (Proyecto): Selecciona tu ID del proyecto de Google Cloud.
    2. Red: Selecciona tu red en el menú desplegable. Si no creaste una red, consulta Cómo crear y administrar redes de VPC para obtener información sobre cómo crear una red.
    3. Rango de IP: Ingresa el rango de IP internas que se pueden asignar a las VM dentro del rango asignado de una red de intercambio de tráfico.
      
      Puedes especificar el rango con la notación de enrutamiento entre dominios sin clases (CIDR) en el formato STARTING_IP/SUBNET_PREFIX_SIZE. Por ejemplo, 192.0.2.0/24 tiene una longitud de prefijo de 24. Los primeros 24 bits del rango de IP se utilizan como la máscara de subred (192.0.2.0), mientras que las posibles direcciones de host varían de 192.0.2.0 a 192.0.2.255.
      
      El valor de la longitud de tu prefijo no debe exceder /29. Si no se especifica un valor para el rango, se asigna automáticamente un valor predeterminado de /24. Si no se especifica ningún valor para la longitud del prefijo, las direcciones IP se asignan automáticamente dentro de la red de VPC con intercambio de tráfico. Si no se especifica ningún valor para la dirección IP, se le asignará automáticamente un rango dentro de la red de VPC con intercambio de tráfico.
      
      Nota: Solo puedes especificar un rango de IP si especificaste una Red. Si especificaste una Red, el Rango de IP es opcional.
Haz clic en Conectar host.

Si tu instancia de Bitbucket Server se encuentra en una red de intercambio de tráfico, la conexión de tu host puede tardar varios minutos en completarse.

Se te redireccionará al panel Conectar repositorio.

Después de crear una conexión de host, tus tokens de acceso personales y el secreto de webhook se almacenarán de forma segura en Secret Manager. Puedes ver y administrar tus secretos en la página Secret Manager.

gcloud

Para conectar el host de Bitbucket Server a Cloud Build con los comandos gcloud, debes ejecutar el comando gcloud alpha builds enterprise-config bitbucketserver create en la terminal. A diferencia de cómo conectar tu host con la consola de Google Cloud, deberás almacenar manualmente los tokens de acceso personal y el secreto de webhook en Secret Manager antes de ejecutar el siguiente comando:

gcloud alpha builds enterprise-config bitbucketserver create
    --name=BITBUCKET_SERVER_CONFIG_NAME \
    --user-name=USERNAME \
    --host-uri=HOST_URI \
    --admin-access-token-secret-version=ADMIN_ACCESS_TOKEN_SECRET_VERSION \
    --read-access-token-secret-version=READ_ACCESS_TOKEN_SECRET_VERSION \
    --webhook-secret-secret-version=WEBHOOK_SECRET_SECRET_VERSION \
    --api-key=API_KEY \
    --peered-network=PEERED_NETWORK \
    --peered-network-ip-range=PEERED_NETWORK_IP_RANGE \
    --ssl-ca-file=SSL_CA_FILE

Donde:

BITBUCKET_SERVER_CONFIG_NAME es el nombre de la configuración del servidor de Bitbucket.
USERNAME es tu nombre de usuario de Bitbucket Server.
HOST_URI es el URI del host de tu instancia de Bitbucket Server.
ADMIN_ACCESS_TOKEN_SECRET_VERSION es el nombre del recurso de tu token de acceso de administrador almacenado en Secret Manager. El formato esperado para los secretos almacenados en Secret Manager es projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}. Puedes especificar latest como tu versión para usar la última versión del secreto. Esto se aplica a cada recurso almacenado en Secret Manager.

READ_ACCESS_TOKEN_SECRET_VERSION es el nombre del recurso de tu token de acceso de lectura almacenado en Secret Manager.
WEBHOOK_SECRET_SECRET_VERSION es el nombre del recurso del secreto de webhook almacenado en Secret Manager.
API_KEY es la clave de API de Google Cloud.
[Opcional] PEERED_NETWORK es la red de VPC a la que te conectarás para las instancias de Bitbucket Server locales. Para obtener más información, consulta Compila repositorios desde Bitbucket Server en una red privada.
PEERED_NETWORK_IP_RANGE es el rango de IP internas al que se pueden asignar las VM dentro del rango asignado de una red de intercambio de tráfico (opcional).

Nota: Solo puedes especificar la marca --peered-network-ip-range cuando la marca --peered-network está configurada. La marca --peered-network-ip-range es opcional cuando se configura la marca --peered-network.
SSL_CA_FILE es la ruta a un archivo local que contiene tu certificado SSL para usar en solicitudes a Bitbucket Server. El certificado debe estar en formato PEM.

API

Para conectar tu host de Bitbucket Server a Cloud Build mediante la API, usa la siguiente plantilla JSON. A diferencia de cuando conectas tu host con la consola de Google Cloud, debes almacenar manualmente tus tokens de acceso personales y el secreto de webhook en Secret Manager antes de llamar a la API:

  {
      "hostUri": "HOST_URI",
      "username": "USERNAME",
      "apiKey": "API_KEY",
      "secrets": {
        "adminAccessTokenVersionName": "ADMIN_ACCESS_TOKEN_SECRET_VERSION",
        "readAccessTokenVersionName": "READ_ACCESS_TOKEN_SECRET_VERSION",
        "webhookSecretVersionName": "WEBHOOK_SECRET_SECRET_VERSION",
      },
      "peeredNetwork": "PEERED_NETWORK",
      "peeredNetworkIpRange": "PEERED_NETWORK_IP_RANGE",
      "sslCa": "SSL_CERTIFICATE"
  }

Donde:

HOST_URI es el URI del host de tu instancia de Bitbucket Server.
USERNAME es tu nombre de usuario de Bitbucket Server.
API_KEY es la clave de API de Google Cloud.
ADMIN_ACCESS_TOKEN_SECRET_VERSION es el nombre del recurso de tu token de acceso de administrador almacenado en Secret Manager. Es posible que debas otorgar la función de Secret Manager a tu cuenta de servicio de Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Para obtener más información, consulta Otorga una función de Secret Manager a tu cuenta de servicio.

Nota: El formato esperado para el nombre del recurso de tu secreto almacenado en Secret Manager es projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}. Puedes especificar latest como tu versión para usar la última versión del secreto. Esto se aplica a cada recurso almacenado en Secret Manager.
READ_ACCESS_TOKEN_SECRET_VERSION es el nombre del recurso de tu token de acceso de lectura almacenado en Secret Manager.
WEBHOOK_SECRET_SECRET_VERSION es el nombre del recurso del secreto de webhook almacenado en Secret Manager.
PEERED_NETWORK es la red de VPC con la que intercambiar tráfico para tus instancias locales de Bitbucket Server (opcional).

Puedes especificar el rango con la notación de enrutamiento entre dominios sin clases (CIDR) con el formato STARTING_IP/SUBNET_PREFIX_SIZE. Por ejemplo, 192.0.2.0/24 tiene una longitud de prefijo de 24. Los primeros 24 bits del rango de IP se usan como la máscara de subred (192.0.2.0), mientras que las direcciones de host posibles varían de 192.0.2.0 a 192.0.2.225.

Nota: El valor de la longitud de tu prefijo no debe exceder /29. Si no se especifica ningún valor para el rango, se asigna automáticamente un valor predeterminado de /24. Si no se especifica ningún valor para la longitud del prefijo, las direcciones IP se asignan de forma automática dentro de la red de VPC con intercambio de tráfico.
PEERED_NETWORK_IP_RANGE es el rango de IP internas al que se pueden asignar las VM dentro del rango asignado de una red de intercambio de tráfico (opcional).

Nota: Solo puedes especificar la marca --peeredNetworkIpRange cuando la marca peeredNetwork está configurada. La marca peeredNetworkIpRange es opcional cuando se configura la marca peeredNetwork.
[Opcional] SSL_CERTIFICATE es el certificado SSL que se usa para tus instancias de Bitbucket Server locales.

Ingresa el siguiente comando curl en la terminal:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/bitbucketServerConfigs/?bitbucketServerConfigId=BITBUCKET_SERVER_CONFIG_NAME -d @config.json

Donde:

PROJECT_NUMBER es el número de proyecto de Cloud.
PROJECT_ID es el ID del proyecto de Cloud.
REGION es la región asociada a tu configuración de Bitbucket Server.
BITBUCKET_SERVER_CONFIG_NAME es el nombre de la configuración del servidor de Bitbucket.

Si el proceso es satisfactorio, el cuerpo de la respuesta contiene una instancia nueva de Operation.

Ingresa el siguiente comando curl en la terminal:

  curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID

Donde:

PROJECT_NUMBER es el número de proyecto de Cloud.
PROJECT_ID es el ID del proyecto de Cloud.
REGION es la región asociada a tu configuración de Bitbucket Server.
OPERATION_ID es el ID de la operación de creación de la configuración de Bitbucket Server.

Es posible que debas seguir ejecutando el comando de la API GetOperation hasta que la respuesta contenga done: true, que indica que se completó la operación. Si la configuración de Bitbucket Server se creó correctamente, podrás verla en el campo response.value. De lo contrario, consulta el campo error para obtener un informe de error detallado.

¿Qué sigue?

Obtén más información sobre cómo conectar un repositorio de Bitbucket Server.
Aprende a realizar implementaciones azul-verde en Compute Engine.