Compartir vía

Compilación de repositorios de Bitbucket Cloud

  • Artículo

Azure DevOps Services

Azure Pipelines puede crear y validar automáticamente todas las solicitudes de incorporación de cambios y confirmaciones en el repositorio de Bitbucket Cloud. En este artículo se describe cómo configurar la integración entre Bitbucket Cloud y Azure Pipelines.

Bitbucket y Azure Pipelines son dos servicios independientes que se integran bien juntos. Los usuarios de Bitbucket Cloud no obtienen acceso automáticamente a Azure Pipelines. Se deben agregar explícitamente a Azure Pipelines.

Acceso a los repositorios de Bitbucket

Para crear una nueva canalización, primero seleccione un repositorio de Bitbucket Cloud y, luego, un archivo YAML en ese repositorio. El repositorio en el que existe el archivo YAML se denomina repositorio self. De forma predeterminada, este es el repositorio que compila la canalización.

Más adelante puede configurar la canalización para restaurar un repositorio diferente o varios repositorios. Para información sobre cómo hacerlo, consulte la restauración de varios repositorios.

Se debe conceder a Azure Pipelines acceso a los repositorios para capturar el código durante las compilaciones. Además, el usuario que configura la canalización debe tener acceso de administrador a Bitbucket, ya que esa identidad se usa para registrar un webhook en Bitbucket.

Hay dos tipos de autenticación para conceder a Azure Pipelines acceso a los repositorios de Bitbucket Cloud al crear una canalización.

Tipo de autenticación Canalizaciones ejecutadas mediante
1. OAuth Su identidad personal de Bitbucket.
2. Nombre de usuario y contraseña Su identidad personal de Bitbucket.

Autenticación de OAuth

OAuth es el tipo de autenticación más sencilla con la que empezar a trabajar en repositorios de la cuenta de Bitbucket. Las actualizaciones de estado de Bitbucket se realizarán en nombre de su identidad personal de Bitbucket. Para que las canalizaciones sigan funcionando, el acceso al repositorio debe permanecer activo.

Para usar OAuth, inicie sesión en Bitbucket cuando se le solicite durante la creación de la canalización. A continuación, haga clic en Autorizar para realizar la autorización con OAuth. Se guardará una conexión OAuth en su proyecto de Azure DevOps para su uso posterior, así como para su uso en la canalización que se está creando.

Nota:

El número máximo de repositorios de Bitbucket que la interfaz de usuario de Azure DevOps Services puede cargar es de 2000.

Autenticación de contraseña

Las compilaciones y las actualizaciones de estado de Bitbucket se realizarán en nombre de su identidad personal. Para que las compilaciones sigan funcionando, el acceso al repositorio debe permanecer activo.

Para crear una conexión con contraseña, visite Conexiones de servicio en la configuración del proyecto de Azure DevOps. Cree una nueva conexión de servicio de Bitbucket y proporcione el nombre de usuario y la contraseña para conectarse al repositorio de Bitbucket Cloud.

Desencadenadores de integración continua

Los desencadenadores de integración continua (CI) hacen que una canalización se ejecute siempre que inserte una actualización en las ramas especificadas o inserte etiquetas especificadas.

Las canalizaciones YAML se configuran de forma predeterminada con un desencadenador de CI en todas las ramas, a menos que la opción Deshabilitar desencadenador de CI de YAML implícito, introducida en el sprint 227 de Azure DevOps, esté habilitada. La opción Deshabilitar desencadenador de CI de YAML implícito se puede configurar en el nivel de organización o en el nivel de proyecto. Cuando la opción Deshabilitar desencadenador de CI de YAML implícito está habilitada, los desencadenadores de CI para canalizaciones YAML no están habilitados si la canalización YAML no tiene una sección trigger. De forma predeterminada, Deshabilitar desencadenador de CI de YAML implícito no está habilitada.

Ramas

Puede controlar qué ramas obtienen desencadenadores de CI con una sintaxis simple:

trigger:
- main
- releases/*

Puede especificar el nombre completo de la rama (por ejemplo, main) o un carácter comodín (por ejemplo, releases/*). Consulte Caracteres comodín para obtener información sobre la sintaxis de caracteres comodín.

Nota:

No se pueden usar variables en desencadenadores, ya que las variables se evalúan en tiempo de ejecución (una vez desencadenado el desencadenador).

Nota:

Si usa plantillas para crear archivos YAML, solo puede especificar desencadenadores en el archivo YAML principal para la canalización. No se pueden especificar desencadenadores en los archivos de plantilla.

Para desencadenadores más complejos que usan exclude o batch, debe usar la sintaxis completa tal y como se muestra en el ejemplo siguiente.

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

En el ejemplo anterior, la canalización se desencadenará si se inserta un cambio en main o en cualquier rama de versiones. Sin embargo, no se desencadenará si se realiza un cambio en una rama de versiones que comienza por old.

Si especifica una cláusula exclude sin una cláusula include, es equivalente a especificar * en la cláusula include.

Además de especificar nombres de rama en las listas branches, también puede configurar desencadenadores basados en etiquetas con el formato siguiente:

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

Si no ha especificado ningún desencadenador y la opción Deshabilitar desencadenador de CI de YAML implícito no está habilitada, el valor predeterminado es como si escribiera:

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

Importante

Cuando se especifica un desencadenador, se reemplaza el desencadenador implícito predeterminado y solo se insertan en ramas configuradas explícitamente para incluirse en el desencadenamiento de una canalización. Las inclusiones se procesan primero y, a continuación, se quitan de esa lista.

Ejecuciones de procesamiento por lotes de CI

Si hay muchos miembros del equipo que cargan cambios a menudo, es posible que desee reducir el número de ejecuciones que inicie. Si establece batch en true, cuando se ejecuta una canalización el sistema espera hasta que se completa la ejecución y entonces inicia otra ejecución con todos los cambios que aún no se han compilado.

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

Nota:

batch no se admite en desencadenadores de recursos de repositorio.

Para aclarar este ejemplo, supongamos que insertar A para main hace que se ejecute la canalización anterior. Mientras se ejecuta esa canalización, se realizan inserciones adicionales de B y C en el repositorio. Estas actualizaciones no inician nuevas ejecuciones independientes inmediatamente. Sin embargo, una vez completada la primera ejecución, todas las inserciones hasta ese momento se procesan por lotes y se inicia una nueva ejecución.

Nota:

Si la canalización tiene varios trabajos y fases, la primera ejecución todavía debe alcanzar un estado terminal completando u omitiendo todos sus trabajos y fases antes de que se pueda iniciar la segunda ejecución. Por este motivo, debe tener cuidado al usar esta característica en una canalización con varias fases o aprobaciones. Si quiere procesar por lotes las compilaciones en tales casos, se recomienda dividir el proceso de CI / CD en dos canalizaciones: una para la compilación (con procesamiento por lotes) y otra para las implementaciones.

Rutas de acceso

Puede especificar rutas de acceso de archivo para incluir o excluir.

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

Al especificar rutas de acceso, debe especificar explícitamente las ramas en las que se desencadenará si usa Azure DevOps Server 2019.1 o versiones anteriores. No se puede desencadenar una canalización solo con un filtro de ruta de acceso; también debe tener un filtro para ramas y los archivos modificados que coincidan con el filtro de ruta de acceso deben ser de una rama que coincida con el filtro para ramas. Si usa Azure DevOps Server 2020 o posterior, puede omitir el filtro branches de todas las ramas junto con el filtro de ruta de acceso.

Se admiten caracteres comodín para los filtros de ruta de acceso. Por ejemplo, puede incluir todas las rutas de acceso que coincidan con src/app/**/myapp*. Puede usar caracteres comodín (**, * o ?)) al especificar filtros de ruta de acceso.

  • Las rutas de acceso siempre se especifican en relación a la raíz del repositorio.
  • Si no establece filtros de ruta de acceso, la carpeta raíz del repositorio se incluye implícitamente de forma predeterminada.
  • Si excluye una ruta de acceso, tampoco puede incluirla a menos que la especifique en una carpeta más profunda. Por ejemplo, si excluye /tools, puede incluir /tools/trigger-runs-on-these.
  • El orden de los filtros de ruta de acceso no es importante.
  • Las rutas de acceso de Git distinguen mayúsculas de minúsculas. Asegúrese de usar mayúsculas o minúsculas de manera idéntica a las carpetas reales.
  • No se pueden usar variables en las rutas de acceso, ya que las variables se evalúan en tiempo de ejecución (después de que se haya activado el desencadenador).

Nota:

En el caso de los repositorios de Bitbucket Cloud, el uso de la sintaxis branches es la única manera de especificar desencadenadores de etiquetas. La sintaxis tags: no se admite para Bitbucket.

Excluirse de la integración continua

Deshabilitación del desencadenador de CI

Puede optar por no participar en desencadenadores de CI por completo especificando trigger: none.

# A pipeline with no CI trigger
trigger: none

Importante

Al insertar un cambio en una rama, se evalúa el archivo YAML de esa rama para determinar si se debe iniciar una ejecución de integración continua.

Omisión de la integración continua para confirmaciones individuales

También puede indicar a Azure Pipelines que omita la ejecución de una canalización que normalmente desencadenaría una inserción. Solo tiene que incluir [skip ci] en el mensaje o descripción de cualquiera de las confirmaciones que forman parte de una inserción y Azure Pipelines omitirá la ejecución de CI para esta inserción. También puede usar algunas de las variaciones siguientes.

  • [skip ci] o [ci skip]
  • skip-checks: true o skip-checks:true
  • [skip azurepipelines] o [azurepipelines skip]
  • [skip azpipelines] o [azpipelines skip]
  • [skip azp] o [azp skip]
  • ***NO_CI***

Uso del tipo de desencadenador en condiciones específicas

Es un escenario común para ejecutar diferentes pasos, trabajos o fases en la canalización en función del tipo de desencadenador que inició la ejecución. Puede hacerlo mediante la variable Build.Reason del sistema. Por ejemplo, agregue la siguiente condición al paso, trabajo o fase para excluirla de las validaciones de PR.

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

Comportamiento de los desencadenadores cuando se crean nuevas ramas

Es habitual configurar varias canalizaciones para el mismo repositorio. Por ejemplo, puede que tenga una canalización para compilar los documentos de la aplicación y otra para compilar el código fuente. Puede configurar desencadenadores de CI con filtros para ramas adecuados y filtros de ruta de acceso en cada una de estas canalizaciones. Por ejemplo, puede que desee que una canalización se desencadene al insertar una actualización en la carpeta docs y otra para desencadenarla al insertar una actualización en el código de la aplicación. En estos casos, debe comprender cómo se desencadenan las canalizaciones cuando se crea una nueva rama.

Este es el comportamiento al insertar una nueva rama (que coincide con los filtros para ramas) en el repositorio:

  • Si la canalización tiene filtros de ruta de acceso, solo se desencadenará si la nueva rama tiene cambios en los archivos que coinciden con ese filtro de ruta de acceso.
  • Si la canalización no tiene filtros de ruta de acceso, se desencadenará aunque no haya cambios en la nueva rama.

Caracteres comodín

Al especificar una rama, etiqueta o ruta de acceso, puede usar un nombre exacto o un carácter comodín. Los patrones de caracteres comodín permiten * coincidencias con cero o más caracteres y ? con un solo carácter.

  • Si inicia el patrón con * en una canalización de YAML, debe encapsular el patrón entre comillas, como "*-releases".
  • Para ramas y etiquetas:
    • Un carácter comodín puede aparecer en cualquier parte del patrón.
  • Para rutas de acceso:
    • En Azure DevOps Server 2022 y versiones posteriores, incluida Azure DevOps Services, un carácter comodín puede aparecer en cualquier parte de un patrón de ruta de acceso y puede usar * o ?.
    • En Azure DevOps Server 2020 y versiones anteriores, puede incluirlo * como carácter final, pero no realiza nada diferente a especificar el nombre del directorio por sí mismo. Es posible que no pueda incluirlo* en medio de un filtro de ruta de acceso y que no pueda usar ?.
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

Desencadenadores de solicitud de incorporación de cambios

Los desencadenadores de solicitud de incorporación de cambios (PR) hacen que se ejecute una canalización cada vez que se abre una solicitud de incorporación de cambios con una de las ramas de destino especificadas, o bien cuando se realizan actualizaciones en esa solicitud de incorporación de cambios.

Ramas

Puede especificar las ramas de destino al validar las solicitudes de incorporación de cambios. Por ejemplo, para validar las solicitudes de incorporación de cambios destinadas a master y releases/*, puede usar el siguiente desencadenador pr.

pr:
- main
- releases/*

Esta configuración inicia una nueva ejecución la primera vez que se crea una solicitud de incorporación de cambios y después de cada actualización realizada en ella.

Puede especificar el nombre completo de la rama (por ejemplo, master) o un carácter comodín (por ejemplo, releases/*).

Nota:

No se pueden usar variables en desencadenadores, ya que las variables se evalúan en tiempo de ejecución (una vez desencadenado el desencadenador).

Nota:

Si usa plantillas para crear archivos YAML, solo puede especificar desencadenadores en el archivo YAML principal para la canalización. No se pueden especificar desencadenadores en los archivos de plantilla.

Cada nueva ejecución compila la confirmación más reciente desde la rama de origen de la solicitud de incorporación de cambios. Esto es diferente a cómo Azure Pipelines compila solicitudes de incorporación de cambios en otros repositorios (por ejemplo, Azure Repos o GitHub), donde se compila la confirmación de combinación. Por desgracia, Bitbucket no expone información sobre la confirmación de combinación, que contiene el código combinado entre las ramas de origen y de destino de la solicitud de incorporación de cambios.

Si no aparece ningún desencadenador pr en el archivo YAML, las validaciones de solicitudes de incorporación de cambios se habilitan automáticamente para todas las ramas, como si escribiera el siguiente desencadenador pr. Esta configuración desencadena una compilación cuando se crea cualquier solicitud de incorporación de cambios y cuando las confirmaciones entran en la rama de origen de cualquier solicitud de incorporación de cambios activa.

pr:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

Importante

Cuando se especifica un desencadenador pr, este reemplaza al desencadenador pr implícito predeterminado, y solo las inserciones en las ramas configuradas explícitamente para incluirse desencadenarán una canalización.

En el caso de desencadenadores más complejos que necesitan excluir determinadas ramas, debe usar la sintaxis completa, como se muestra en el ejemplo siguiente.

# specific branch
pr:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

Rutas de acceso

Puede especificar rutas de acceso de archivo para incluir o excluir. Por ejemplo:

# specific path
pr:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

Sugerencias:

  • No se admiten caracteres comodín con filtros de ruta de acceso.
  • Las rutas de acceso siempre se especifican en relación con la raíz del repositorio.
  • Si no establece filtros de ruta de acceso, la carpeta raíz del repositorio se incluye implícitamente de forma predeterminada.
  • Si excluye una ruta de acceso, tampoco puede incluirla a menos que la especifique en una carpeta más profunda. Por ejemplo, si excluye /tools, puede incluir /tools/trigger-runs-on-these.
  • El orden de los filtros de ruta de acceso no es importante.
  • Las rutas de acceso de Git distinguen mayúsculas de minúsculas. Asegúrese de usar mayúsculas o minúsculas de manera idéntica a las carpetas reales.
  • No se pueden usar variables en las rutas de acceso, ya que las variables se evalúan en tiempo de ejecución (después de que se haya activado el desencadenador).

Varias actualizaciones de solicitud de incorporación de cambios

Puede especificar si las actualizaciones adicionales de una solicitud de incorporación de cambios deben cancelar las ejecuciones de validación en curso de la misma solicitud de incorporación de cambios. El valor predeterminado es true.

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

Excluirse de la validación de solicitudes de incorporación de cambios

Puede excluirse de la validación de solicitudes de incorporación de cambios por completo especificando pr: none.

# no PR triggers
pr: none

Para más información, consulte Desencadenador de solicitud de incorporación de cambios en el esquema YAML.

Nota:

Si el desencadenador pr no se activa, asegúrese de que no ha invalidado los desencadenadores de solicitud de incorporación de cambios en la interfaz de usuario.

Ejecuciones informativas

Una ejecución informativa indica que Azure DevOps no pudo recuperar el código fuente de una canalización YAML. La recuperación del código fuente se produce en respuesta a eventos externos, por ejemplo, una confirmación insertada. También ocurre en respuesta a los desencadenadores internos, por ejemplo, para comprobar si hay cambios en el código e iniciar una ejecución programada o no. La recuperación del código fuente puede producir un error por varias razones, siendo una de las más frecuentes la limitación de solicitudes por parte del proveedor del repositorio de Git. La existencia de una ejecución informativa no significa necesariamente que Azure DevOps vaya a ejecutar la canalización.

Una ejecución informativa es similar a la de la captura de pantalla siguiente.

Screenshot of an informational pipeline run.

Puede reconocer una ejecución informativa por los atributos siguientes:

  • El estado es Canceled.
  • La duración es < 1s.
  • El nombre de la ejecución contiene uno de los siguientes textos:
    • Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
    • Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
    • Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
    • Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
  • El nombre de la ejecución contiene generalmente el error de BitBucket o GitHub que hizo que no se pudiera cargar la canalización de YAML.
  • Sin fases, trabajos o pasos

Más información sobre las ejecuciones informativas.

Limitaciones

Azure Pipelines carga un máximo de 2000 ramas de un repositorio en listas desplegables del Portal de Azure Devops, por ejemplo, en la rama Predeterminada para la configuración de compilaciones manuales y programadas, o al elegir una rama al ejecutar una canalización manualmente. Si no ve la rama deseada en la lista, escriba manualmente el nombre de la rama deseada.

Preguntas más frecuentes

Los problemas relacionados con la integración de Bitbucket se dividen en las siguientes categorías:

Desencadenadores con errores

Acabo de crear una nueva canalización de YAML con desencadenadores de CI/PR, pero la canalización no se desencadena.

Siga cada uno de estos pasos para solucionar problemas relacionados con los desencadenadores con errores:

  • ¿Se reemplazan los desencadenadores CI o PR YAML por la configuración de las canalizaciones en la interfaz de usuario? Al editar la canalización, elija ... y, luego, Desencadenadores.

    Pipeline settings UI.

    Compruebe la opción de configuración Invalidar el desencadenador de YAML desde aquí para los tipos de desencadenador (integración continua o validación de solicitudes de incorporación de cambios) disponibles para el repositorio.

    Override YAML trigger from here.

  • Los webhooks se usan para comunicar actualizaciones de Bitbucket a Azure Pipelines. En Bitbucket, vaya a la configuración del repositorio y, luego, a Webhooks. Compruebe que existen los webhooks.

  • ¿La canalización está en pausa o deshabilitada? Abra el editor de la canalización y seleccione Configuración para comprobarlo. Si la canalización está en pausa o deshabilitada, los desencadenadores no funcionan.

  • ¿Ha actualizado el archivo YAML en la rama correcta? Si inserta una actualización en una rama, el archivo YAML de esa misma rama rige el comportamiento de la integración continua. Si inserta una actualización en una rama de origen, el archivo YAML resultante de combinar la rama de origen con la rama de destino rige el comportamiento de la solicitud de incorporación de cambios. Asegúrese de que el archivo YAML de la rama correcta tiene la configuración de integración continua o solicitud de incorporación de cambios necesaria.

  • ¿Ha configurado el desencadenador correctamente? Al definir un desencadenador de YAML, puede especificar cláusulas de inclusión y exclusión de ramas, etiquetas y rutas de acceso. Asegúrese de que la cláusula de inclusión coincida con los detalles de la confirmación y que la cláusula de exclusión no los excluya. Compruebe la sintaxis de los desencadenadores y asegúrese de que es correcta.

  • ¿Ha usado variables para definir el desencadenador o las rutas de acceso? Esto no se admite.

  • ¿Ha usado plantillas para el archivo YAML? Si es así, asegúrese de que los desencadenadores estén definidos en el archivo YAML principal. No se admiten desencadenadores definidos dentro de los archivos de plantilla.

  • ¿Ha excluido las ramas o rutas de acceso en las que insertó los cambios? Para comprobarlo, inserte un cambio en una ruta de acceso incluida en una rama incluida. Tenga en cuenta que las rutas de acceso de los desencadenadores distinguen mayúsculas de minúsculas. Asegúrese de usar las mismas mayúsculas o minúsculas que en las carpetas reales al especificar las rutas de acceso en los desencadenadores.

  • ¿Acaba de insertar una nueva rama? Si es así, es posible que la nueva rama no inicie una nueva ejecución. Consulte la sección "Comportamiento de los desencadenadores cuando se crean nuevas ramas".

Mis desencadenadores de integración continua o de solicitud de incorporación de cambios funcionaban bien. Sin embargo, ahora no funcionan.

En primer lugar, siga los pasos de solución de problemas de la pregunta anterior. A continuación, siga estos pasos adicionales:

  • ¿Tiene conflictos de combinación en la solicitud de incorporación de cambios? Si una solicitud de incorporación de cambios no ha desencadenado una canalización, ábrala y compruebe si tiene un conflicto de combinación. Resuelva el conflicto de combinación.

  • ¿Experimenta un retraso en el procesamiento de eventos de inserción o de solicitud de incorporación de cambios? Para comprobarlo, observe si el problema es específico de una sola canalización o es común a todas las canalizaciones o repositorios del proyecto. Si una actualización de inserción o de solicitud de incorporación de cambios en cualquiera de los repositorios muestra este síntoma, podríamos estar experimentando retrasos en el procesamiento de los eventos de actualización. Compruebe si estamos experimentando una interrupción del servicio en nuestra página de estado. Si la página de estado muestra un problema, nuestro equipo debe haber empezado a trabajar en él. Compruebe la página con frecuencia por si hay actualizaciones del problema.

No quiero que los usuarios invaliden la lista de ramas de los desencadenadores cuando actualizan el archivo YAML. ¿Cómo puedo hacerlo?

Los usuarios con permiso para contribuir al código pueden actualizar el archivo YAML e incluir o excluir ramas adicionales. Como resultado, los usuarios pueden incluir su propia característica o rama de usuario en su archivo YAML e insertar esa actualización en una característica o rama de usuario. Esto puede hacer que la canalización se desencadene para todas las actualizaciones de esa rama. Si desea evitar este comportamiento, puede hacer lo siguiente:

  1. Edite la canalización en la interfaz de usuario de Azure Pipelines.
  2. Vaya al menú Desencadenadores.
  3. Seleccione Invalidar el desencadenador de integración continua de YAML desde aquí.
  4. Especifique las ramas que se van a incluir o excluir para el desencadenador.

Al seguir estos pasos, se omiten los desencadenadores de integración continua especificados en el archivo YAML.

Versión incorrecta

En la canalización se usa una versión incorrecta del archivo YAML. ¿A qué se debe?

  • En el caso de los desencadenadores de integración continua, el archivo YAML que se encuentra en la rama que va a insertar se evalúa para ver si se debe ejecutar una compilación de integración continua.
  • En el caso de los desencadenadores de solicitud de incorporación de cambios, el archivo YAML resultante de combinar las ramas de origen y destino de la solicitud de incorporación de cambios se evalúa para ver si se debe ejecutar una compilación de solicitud de incorporación de cambios.