Compilación de repositorios Git de Azure Repos o Git de TFS

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Azure Pipelines puede crear y validar automáticamente cada solicitud de extracción y confirmarla en el repositorio Azure Repos Git.

Elija un repositorio para compilarlo

YAML

Para crear una nueva canalización, primero seleccione un repositorio y, a continuación, un archivo YAML en ese repositorio. El repositorio en el que está presente 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.

Clásico

Al crear una canalización para elegir el repositorio que se va a compilar, seleccione primero el proyecto al que pertenece el repositorio. Después, seleccione el repositorio.

Para clonar repositorios adicionales como parte de la canalización:

• Si el repositorio está en el mismo proyecto que la canalización o si el token de acceso (que se explica a continuación) tiene acceso al repositorio en un proyecto diferente, use el siguiente comando:

  git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" <clone URL>

  Para poder usar System.AccessToken en un script, primero debe ponerlo a disposición de este. Para ello, seleccione el trabajo en la pestaña Tareas del editor, seleccione Opciones adicionales en el panel derecho y active la opción Permitir que los scripts accedan al token de OAuth.

• Si el token de acceso (que se explica a continuación) no tiene acceso al repositorio:

  1. Obtenga un token de acceso personal (PAT) con Code (read) ámbito y prefijo con PAT:
  2. Codifique en Base64 esta cadena para crear un token de autenticación básico.
  3. Agregue un script en la canalización con el siguiente comando para clonar ese repositorio git clone -c http.extraheader="AUTHORIZATION: basic <BASIC_AUTH_TOKEN>" <clone URL>

Se debe conceder acceso a Azure Pipelines a los repositorios para desencadenar sus compilaciones y capturar su código durante las compilaciones. Normalmente una canalización tiene acceso a los repositorios del mismo proyecto. Sin embargo, si desea acceder a repositorios en un proyecto diferente, debe actualizar los permisos concedidos a los tokens de acceso de trabajo.

Desencadenadores CI

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.

YAML

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 rutas de acceso, ya que las variables se evalúan en tiempo de ejecución (después de que se haya activado el desencadenador).

Etiquetas

Además de especificar etiquetas en las listas branches como se describe en la sección anterior, puede especificar directamente etiquetas para incluir o excluir:

# specific tag
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

Si no especifica ningún desencadenador de etiqueta, las etiquetas no desencadenarán canalizaciones de forma predeterminada.

Importante

Si especifica etiquetas en combinación con filtros para ramas, el desencadenador se activará si se cumple el filtro para ramas o si se cumple el filtro de etiquetas. Por ejemplo, si una etiqueta insertada satisface el filtro para ramas, la canalización se desencadena incluso si el filtro de etiquetas excluye la etiqueta, ya que la inserción satisface el filtro para ramas.

No participar en CI

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.

Clásico

Seleccione Habilitar integración continua en la pestaña Desencadenadores para habilitar este desencadenador si quiere que la compilación se ejecute cada vez que alguien inserte código en el repositorio.

Cambios por lotes

Active esta casilla si hay muchos miembros del equipo que cargan cambios con frecuencia y desea reducir el número de compilaciones que está ejecutando. Si selecciona esta opción, cuando se ejecuta una compilación el sistema espera hasta que se completa la ejecución y, a continuación, pone en cola otra ejecución de todos los cambios que aún no se hayan compilado.

Puede procesar por lotes los cambios y compilarlos juntos.

Nota:

Si usa el procesamiento por lotes con una canalización YAML de varias fases, una ejecución debe alcanzar un estado terminal antes de que se pueda iniciar la siguiente. Esto a menudo no es deseable, ya que una canalización de varias fases puede pasar por aprobaciones y fases de implementación de larga duración. En estos casos, se recomienda seguir una de estas soluciones:

• no usar procesamiento por lotes
• dividir la canalización en dos canalizaciones independientes: una para CI y una para CD
• establecer las condiciones adecuadas en las fases para omitirlas y hacer que una ejecución finalice rápidamente

Filtros para ramas

Puede especificar las ramas en las que desea desencadenar compilaciones. Si quiere usar caracteres comodín, escriba la especificación de la rama (por ejemplo, features/modules/*) y presione Entrar.

Filtros de ruta de acceso

Si el repositorio de Git está en Azure Repos o TFS, también puede especificar filtros de ruta de acceso para reducir el conjunto de archivos que desea que desencadenen una compilación.

Sugerencias:

• 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.

Ejemplo

Por ejemplo, quiere que la compilación se desencadene mediante cambios en main y en la mayoría de las ramas de características, pero no en todas. Tampoco desea que las compilaciones se desencadenen mediante cambios en los archivos de la carpeta de herramientas.

Omisión de CI para inserciones 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 PR

Los desencadenadores de solicitud de incorporación de cambios (PR) hacen que una canalización se ejecute siempre que abra una solicitud de incorporación de cambios o al insertar cambios en ella. En Azure Repos Git, esta funcionalidad se implementa mediante directivas de rama. Para habilitar la validación de PR, vaya a las directivas de rama de la rama deseada y configure la directiva de validación de compilación para esa rama. Para obtener más información, consulte Configuración de directivas de rama.

Si tiene una solicitud de incorporación de cambios abierta e inserta cambios en su rama de origen, se pueden ejecutar varias canalizaciones:

• Las canalizaciones especificadas por la directiva de validación de compilación de la rama de destino se ejecutarán en la confirmación de combinación (el código combinado entre las ramas de origen y de destino de la solicitud de incorporación de cambios), independientemente de si existen confirmaciones insertadas cuyos mensajes o descripciones contienen [skip ci] (o cualquiera de sus variantes).
• Las canalizaciones desencadenadas por cambios en la rama de origen de la solicitud de incorporación de cambios, si no hay confirmaciones insertadas cuyos mensajes o descripciones contienen [skip ci] (o cualquiera de sus variantes). Si al menos una confirmación insertada contiene [skip ci], las canalizaciones no se ejecutarán.

Por último, después de combinar la solicitud de incorporación de cambios, Azure Pipelines ejecutará las canalizaciones de CI desencadenadas por inserciones en la rama de destino, incluso si algunos de los mensajes o descripciones de las confirmaciones combinadas contienen [skip ci] (o cualquiera de sus variantes).

Nota:

Debe ser administrado del proyecto para configurar compilaciones de validación para un repositorio de Git de Azure Repos.

Nota:

Las solicitudes del borrador de incorporación de cambios no desencadenan una canalización aunque configure una directiva de rama.

Validación de contribuciones de bifurcaciones

La compilación de solicitudes de incorporación de cambios de bifurcaciones de Azure Repos es igual que la compilación de solicitudes de incorporación de cambios en el mismo repositorio o proyecto. Solo puede crear bifurcaciones dentro de la misma organización de la que forma parte el proyecto.

Ámbito de autorización del trabajo de compilación

Azure Pipelines proporciona varias opciones de seguridad para configurar el ámbito de autorización del trabajo con el que se ejecutan las canalizaciones.

• Limitar el ámbito de autorización del trabajo al proyecto actual
• Proteger el acceso a repositorios en canalizaciones YAML

Limitar el ámbito de autorización del trabajo al proyecto actual

Azure Pipelines proporciona dos configuraciones para limitar el ámbito de autorización de trabajo al proyecto actual:

• Limitar el ámbito de autorización del trabajo al proyecto actual para canalizaciones que no son de versión: esta configuración se aplica a las canalizaciones de YAML y a las canalizaciones de compilación clásicas. Esta configuración no se aplica a las canalizaciones de versión clásicas.
• Limitar el ámbito de autorización del trabajo al proyecto actual para canalizaciones de versión: esta configuración solo se aplica a las canalizaciones de versión clásicas.

Las canalizaciones se ejecutan con tokens de acceso con ámbito de recopilación a menos que esté habilitada la configuración pertinente para el tipo de canalización. La configuración Limitar el ámbito de autorización del trabajo permite reducir el ámbito de acceso de todas las canalizaciones al proyecto actual. Esto puede afectar a la canalización si accede a un repositorio de Git de Azure Repos en un proyecto diferente en la organización.

Si el repositorio de Git de Azure Repos se encuentra en un proyecto diferente de la canalización y la configuración Limitar el ámbito de autorización del trabajo para el tipo de canalización está habilitada, debe conceder permiso a la identidad del servicio de compilación para la canalización al segundo proyecto. Para más información, consulte Administración de permisos de cuenta de servicio de compilación.

Para más información sobre Limitar el ámbito de autorización del trabajo, consulte Descripción de los tokens de acceso al trabajo.

Proteger el acceso a repositorios en canalizaciones YAML

Las canalizaciones pueden acceder a cualquier repositorio de Azure DevOps en proyectos autorizados, como se describe en la sección anterior Limitar el ámbito de autorización del trabajo al proyecto actual, a menos que esté habilitado Proteger el acceso a repositorios en canalizaciones YAML. Con esta opción habilitada, puede reducir el ámbito de acceso de todas las canalizaciones solo a repositorios de Azure DevOps a los que hace referencia explícitamente con un paso checkout o una instrucción uses en el trabajo de canalización que usa ese repositorio.

Para configurar esta opción, vaya a Canalizaciones y Configuración en Configuración de organización o Configuración del proyecto. Si está habilitado en el nivel de organización, la configuración está atenuada y no está disponible en el nivel de configuración del proyecto.

Importante

Proteger el acceso a repositorios en canalizaciones YAML está habilitado de forma predeterminada para las nuevas organizaciones y proyectos creados a partir de mayo de 2020. Cuando se habilita Proteger el acceso a repositorios en canalizaciones YAML, las canalizaciones de YAML deben hacer referencia explícitamente a los repositorios de Git de Azure Repos que quiera usar en la canalización como paso de desprotección en el trabajo que usa el repositorio. No podrá recuperar códigos mediante tareas de scripting y comandos Git para un repositorio de Git de Azure Repos a menos que se haga referencia a ese repositorio explícitamente.

Hay algunas excepciones en las que no es necesario hacer referencia explícita a un repositorio de Git de Azure Repos antes de usarlo en la canalización cuando está habilitado Proteger el acceso a repositorios en canalizaciones YAML.

• Si no tiene un paso explícito de restauración en la canalización, es como si tuviera un paso checkout: self y el repositorio self se restaurara.
• Si usa un script para realizar operaciones de solo lectura en un repositorio de un proyecto público, no es necesario hacer referencia al repositorio de proyectos públicos en un paso checkout.
• Si usa un script que proporciona su propia autenticación al repositorio, como PAT, no es necesario hacer referencia a ese repositorio en un paso checkout.

Por ejemplo, cuando se habilita Proteger el acceso a repositorios en canalizaciones YAML, si la canalización está en el repositorio FabrikamProject/Fabrikam de la organización y desea usar un script para restaurar el repositorio FabrikamProject/FabrikamTools, debe hacer referencia a este repositorio en un paso checkout o con una instrucción uses.

Si ya ha restaurado el repositorio FabrikamTools en la canalización mediante un paso de restauración, puede usar posteriormente scripts para interactuar con ese repositorio.

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo
# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools
steps:
- script: # Do something with that repo like clone it

Nota:

En muchos escenarios se puede aprovechar la restauración de varios repositorios, lo que elimina la necesidad de usar scripts para consultar repositorios adicionales en la canalización. Para obtener más información, consulte Restauración de repositorios múltiples en la canalización.

Restauración

Cuando se desencadena una canalización, Azure Pipelines extrae el código fuente del repositorio de Git de Azure Repos. Puede controlar varios aspectos de su funcionamiento.

Nota:

Al incluir un paso de restauración en la canalización, se ejecuta el siguiente comando: git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1. Si esto no satisface sus necesidades, puede optar por excluir la restauración integrada con checkout: none, y a continuación usar una tarea de script para realizar su propia restauración.

Versión preferida de Git

El agente de Windows incluye su propia copia de Git. Si prefiere proporcionar su propio Git en lugar de usar la copia incluida, establezca System.PreferGitFromPath en true. Esta configuración siempre es TRUE en agentes que no son de Windows.

Restauración de rutas de acceso

YAML

Si va a restaurar un único repositorio, el código fuente se restaurará en un directorio denominado s de forma predeterminada. En el caso de las canalizaciones YAML, puede cambiar esto especificando checkout con un path. La ruta de acceso especificada es relativa a $(Agent.BuildDirectory). Por ejemplo: si el valor de la ruta de acceso de restauración es mycustompath y $(Agent.BuildDirectory) es C:\agent\_work\1, el código fuente se restaurará en C:\agent\_work\1\mycustompath.

Si usa varios pasos checkout, restaura varios repositorios y no especifica explícitamente la carpeta mediante path, cada repositorio se coloca en una subcarpeta s llamada después del repositorio. Por ejemplo, si restaura dos repositorios llamados tools y code, el código fuente se restaurará en C:\agent\_work\1\s\tools y C:\agent\_work\1\s\code.

Tenga en cuenta que el valor de la ruta de restauración no se puede establecer para subir los niveles de directorio por encima de $(Agent.BuildDirectory), por lo que path\..\anotherpath dará como resultado una ruta de restauración válida (es decir, C:\agent\_work\1\anotherpath), y no un valor como ..\invalidpath (es decir, C:\agent\_work\invalidpath).

Puede configurar el valor path en el paso de restauración de la canalización.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Clásico

Esta configuración no se puede configurar en el editor clásico. El código fuente se restaurará en un directorio denominado s, que es relativo a $(Agent.BuildDirectory). Por ejemplo: si $(Agent.BuildDirectory) es C:\agent\_work\1, el código fuente se restaurará en C:\agent\_work\1\mycustompath.

Submódulos

YAML

Puede configurar el valor submodules en el paso de restauración de la canalización si desea descargar archivos de submódulos.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Clásico

Puede configurar el valor submódulos de las propiedades de la tarea Obtener orígenes de la canalización si desea descargar archivos de submódulos.

La canalización de compilación restaurará los submódulos de Git siempre que sean:

• Sin autenticar: Un repositorio público y no autenticado sin credenciales necesarias para clonar o capturar.

• Autenticado:

  • Incluido en el mismo proyecto que el repositorio de Git de Azure Repos especificado anteriormente. Las mismas credenciales que usa el agente para obtener los orígenes del repositorio principal se usan para obtener los orígenes de los submódulos.

  • Se ha agregado mediante una dirección URL relativa al repositorio principal. Por ejemplo

    • Esta se restauraría: git submodule add ../../../FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

      En este ejemplo, el submódulo hace referencia a un repositorio (FabrikamFiber) en la misma organización de Azure DevOps, pero en un proyecto diferente (FabrikamFiberProject). Las mismas credenciales que usa el agente para obtener los orígenes del repositorio principal se usan para obtener los orígenes de los submódulos. Esto requiere que el token de acceso al trabajo tenga acceso al repositorio en el segundo proyecto. Si ha restringido el token de acceso al trabajo como se explica en la sección anterior, no podrá hacerlo. Puede permitir que el token de acceso al trabajo acceda al repositorio del segundo proyecto mediante (a) conceder explícitamente acceso a la cuenta del servicio de compilación del proyecto en el segundo proyecto o (b) mediante tokens de acceso con ámbito de recopilación en lugar de tokens de ámbito de proyecto para toda la organización. Para más información sobre estas opciones y sus implicaciones de seguridad, consulte Acceso a repositorios, artefactos y otros recursos.

    • Este no se restauraría: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

Alternativa al uso de la opción Desprotección de submódulos

En algunos casos, no se puede usar la opción Desprotección de submódulos. Es posible que tenga un escenario en el que se necesite un conjunto diferente de credenciales para acceder a los submódulos. Esto puede ocurrir, por ejemplo, si el repositorio principal y los repositorios de los submódulos no se almacenan en la misma organización de Azure DevOps o si el token de acceso al trabajo no tiene acceso al repositorio en un proyecto diferente.

Si no puede usar la opción Desprotección de submódulos, puede usar un paso de script personalizado para recuperar submódulos. En primer lugar, obtenga un token de acceso personal (PAT) y añada un prefijo con pat:. A continuación, codifique en Base64 esta cadena con prefijo para crear un token de autenticación básico. Por último, agregue este script a la canalización:

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: Basic <BASE64_ENCODED_STRING>" submodule update --init --recursive

Asegúrese de reemplazar "<BASE64_ENCODED_STRING>" por la cadena "pat:token" codificada en Base64.

Use una variable secreta en el proyecto o la canalización de compilación para almacenar el token de autenticación básico que generó. Use esa variable para rellenar el secreto en el comando de Git anterior.

Nota:

P: ¿Por qué no puedo usar un administrador de credenciales de Git en el agente? R: El almacenamiento de las credenciales de submódulo en un administrador de credenciales de Git instalado en el agente de compilación privado no suele ser efectivo, ya que el administrador de credenciales puede pedir que vuelva a escribir las credenciales cada vez que se actualice el submódulo. Esto no es deseable durante las compilaciones automatizadas cuando la interacción del usuario no es posible.

Sincronizar etiquetas

Importante

La característica de sincronización de etiquetas es compatible con Azure Repos Git a partir de Azure DevOps Server 2022.1.

El paso de restauración usa la opción --tags de recuperar el contenido de un repositorio de Git. Esto hace que el servidor recupere todas las etiquetas, así como todos los objetos a los que apuntan esas etiquetas. Esto aumenta el tiempo para ejecutar la tarea en una canalización, especialmente si tiene un repositorio grande con una serie de etiquetas. Además, el paso de restauración sincroniza las etiquetas incluso cuando se habilita la opción de recuperación superficial, lo que posiblemente acaba con su propósito. Para reducir la cantidad de datos recuperados o extraídos de un repositorio de Git, Microsoft ha agregado una nueva opción para restaurar y controlar el comportamiento de las etiquetas de sincronización. Esta opción está disponible tanto en canalizaciones clásicas como en YAML.

Si desea sincronizar etiquetas al restaurar un repositorio, se puede configurar en YAML estableciendo la propiedad fetchTags y en la interfaz de usuario mediante la configuración de etiquetas de sincronización.

YAML

Puede configurar el valor fetchTags en el paso de desprotección de la canalización.

Para configurar el valor en YAML, establezca la propiedad fetchTags.

steps:
- checkout: self
  fetchTags: true

También puede configurar este valor mediante la opción Etiquetas de sincronización en la interfaz de usuario de configuración de canalización.

1. Edite la canalización de YAML y elija Más acciones y Desencadenadores.

   

2. Elija YAML y Obtener orígenes.

   

3. Configure la opción Etiquetas de sincronización.

   

Nota:

Si establece fetchTags explícitamente en el paso checkout, esa configuración tiene prioridad sobre la configuración de la interfaz de usuario de configuración de canalización.

Clásico

Puede configurar la opción Etiquetas de sincronización de las propiedades de la tarea Obtener orígenes de la canalización.

Comportamiento predeterminado

• En el caso de las canalizaciones existentes creadas antes del lanzamiento del sprint 209 de Azure DevOps, publicada en septiembre de 2022, el valor predeterminado de las etiquetas de sincronización sigue siendo el mismo que el comportamiento existente antes de agregar las opciones de etiquetas de sincronización, que es true.
• En el caso de las nuevas canalizaciones creadas después del sprint 209 de Azure DevOps, el valor predeterminado de las etiquetas de sincronización es false.

Nota:

Si establece fetchTags explícitamente en el paso checkout, esa configuración tiene prioridad sobre la configuración de la interfaz de usuario de configuración de canalización.

Recuperación de cambios superficiales

Es posible que quiera limitar la distancia de la descarga del historial. De hecho, esto da como resultado git fetch --depth=n. Si el repositorio es grande, esta opción podría hacer que la canalización de compilación sea más eficaz. El repositorio puede ser grande si ha estado en uso durante mucho tiempo y tiene un historial considerable. También puede ser grande si ha agregado y eliminado archivos grandes más adelante.

Importante

Las nuevas canalizaciones creadas después de la actualización de sprint 209 de septiembre de 2022 de Azure DevOps tienen habilitada la recuperación de cambios superficiales de forma predeterminada y configurada con una profundidad de 1. Anteriormente, el valor predeterminado no era la recuperación de cambios superficiales. Para comprobar la canalización, vea la configuración de recuperación de cambios superficiales en la interfaz de usuario de configuración de canalización, tal como se describe en la sección siguiente.

YAML

Puede configurar el valor fetchDepth en el paso de restauración de la canalización.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

También puede configurar la profundidad de la recuperación estableciendo la opción Profundidad superficial en la interfaz de usuario de configuración de canalización.

1. Edite la canalización de YAML y elija Más acciones y Desencadenadores.

   

2. Elija YAML y Obtener orígenes.

   

3. Configure el valor de recuperación de cambios superficiales. Desactive Recuperación de cambios superficiales para deshabilitar la recuperación de cambios superficiales o active la casilla y escriba una profundidad para habilitarla.

   

Nota

Si establece fetchDepth explícitamente en el paso checkout, esa configuración tiene prioridad sobre la configuración de la interfaz de usuario de configuración de canalización. Al establecer fetchDepth: 0 se recupera todo el historial y se invalida la configuración derecuperación de cambios superficiales.

Clásico

Puede configurar el valor de la recuperación de cambios superficiales desde las propiedades de la tarea Obtener orígenes de la canalización.

En estos casos, esta opción puede ayudarle a conservar los recursos de red y almacenamiento. También puede ahorrar tiempo. La razón por la que no siempre ahorra tiempo es que, en algunas situaciones, es posible que el servidor tenga que dedicar tiempo a calcular las confirmaciones para descargar a la profundidad que especifique.

Nota

Cuando se inicia la canalización, la rama que se va a compilar se resuelve en un identificador de confirmación. A continuación, el agente recupera la rama y comprueba la confirmación deseada. Hay una ventana pequeña entre resolver una rama en un identificador de confirmación y cuando el agente realiza la restauración. Si la rama se actualiza rápidamente y establece un valor muy pequeño para la recuperación de cambios superficial, es posible que la confirmación no exista cuando el agente intente extraerla. Si esto sucede, aumente la configuración de profundidad de la recuperación de cambios superficial.

No sincronizar orígenes

Es posible que quiera omitir la recuperación de nuevas confirmaciones. Esta opción puede ser útil en los casos en los que desee:

• iniciar, configurar y recuperar en Git con sus propias opciones personalizadas.

• usar una canalización de compilación para ejecutar la automatización (por ejemplo, algunos scripts) y que no dependa del código en el control de versiones.

YAML

Puede configurar la opción No sincronizar orígenes en el paso de desprotección de la canalización estableciendo checkout: none.

steps:
- checkout: none  # Don't sync sources

Clásico

Seleccione la opción No sincronizar orígenes en las propiedades de la tarea Obtener orígenes de la canalización.

Nota

Cuando se usa esta opción, el agente también omite la ejecución de comandos de Git que limpian el repositorio.

Limpiar compilación

Puede realizar diferentes formas de limpieza del directorio de trabajo del agente autohospedado antes de que se ejecute una compilación.

En general, para un rendimiento más rápido de los agentes autohospedados, no limpie el repositorio. En este caso, para obtener el mejor rendimiento, asegúrese de que también está compilando incrementalmente; para ello, deshabilite cualquier opción Limpiar de la tarea o herramienta que esté usando para compilar.

Si necesita limpiar el repositorio (por ejemplo, para evitar problemas causados por archivos residuales de una compilación anterior), se indican las opciones a continuación.

Nota

La limpieza no es eficaz si usa un agente hospedado por Microsoft porque obtendrá un nuevo agente cada vez.

YAML

Puede configurar el valor clean en el paso de desprotección de la canalización.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Cuando clean se establece en true en la canalización de compilación, deshace los cambios en $(Build.SourcesDirectory). Más concretamente, los siguientes comandos de Git se ejecutan antes de recuperar el origen.

git clean -ffdx
git reset --hard HEAD

Para obtener más opciones, puede configurar el valor workspace de un trabajo.

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  ...
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

Esto proporciona las siguientes opciones de limpieza.

• salidas: la misma operación que la configuración de limpieza descrita en la tarea de restauración anterior, además de: elimina y vuelve a crear $(Build.BinariesDirectory). Tenga en cuenta que $(Build.ArtifactStagingDirectory) y $(Common.TestResultsDirectory) siempre se eliminan y se vuelven a crear antes de cada compilación, independientemente de cualquiera de estas configuraciones.

• recursos: elimina y vuelve a crear $(Build.SourcesDirectory). Esto da como resultado el inicio de un repositorio de Git local nuevo para cada compilación.

• todos: elimina y vuelve a crear $(Agent.BuildDirectory). Esto da como resultado el inicio de un repositorio de Git local nuevo para cada compilación.

Clásico

Seleccione la opción de Limpiar en las propiedades de la tarea Obtener orígenes de la canalización y seleccione una de las siguientes opciones.

• Orígenes: la canalización de compilación deshace los cambios en $(Build.SourcesDirectory). Más concretamente, los siguientes comandos de Git se ejecutan antes de recuperar el origen.

  git clean -ffdx
  git reset --hard HEAD
  

• Orígenes y directorio de salida: la misma operación que la opción Orígenes anterior, además de: elimina y vuelve a crear $(Build.BinariesDirectory). Tenga en cuenta que $(Build.ArtifactStagingDirectory) y $(Common.TestResultsDirectory) siempre se eliminan y se vuelven a crear antes de cada compilación, independientemente de cualquiera de estas configuraciones.

• Directorio de orígenes: elimina y vuelve a crear $(Build.SourcesDirectory). Esto da como resultado el inicio de un repositorio de Git local nuevo para cada compilación.

• Todos los directorios de compilación: elimina y vuelve a crear $(Agent.BuildDirectory). Esto da como resultado el inicio de un repositorio de Git local nuevo para cada compilación.

Etiquetar orígenes

Es posible que quiera etiquetar los archivos de código fuente para permitir que su equipo identifique fácilmente qué versión de cada archivo se incluye en la compilación completada. También tiene la opción de especificar si el código fuente debe etiquetarse para todas las compilaciones o solo para compilaciones correctas.

YAML

Actualmente no puede configurar esta opción en YAML, pero puede hacerlo en el editor clásico. Al editar una canalización YAML, puede acceder al editor clásico si elige Desencadenadores en el menú del editor de YAML.

En el editor clásico, elija YAML, elija la tarea Obtener orígenes y, a continuación, configure las propiedades deseadas allí.

Clásico

Puede configurar el valor Orígenes de etiquetas de las propiedades de la tarea Obtener orígenes de la canalización.

En formato de etiquetas puede usar variables definidas por el usuario y predefinidas que tengan un ámbito de "All". Por ejemplo:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

Las cuatro primeras variables están predefinidas. My.Variable puede definirlas en la pestaña variables.

La canalización de compilación etiqueta los orígenes con una etiqueta Git.

Algunas variables de compilación pueden producir un valor que no sea una etiqueta válida. Por ejemplo, variables como $(Build.RequestedFor) y $(Build.DefinitionName) pueden contener espacios en blanco. Si el valor contiene espacios en blanco, la etiqueta no se crea.

Una vez que la canalización de compilación etiquete los orígenes, se agrega automáticamente un artefacto con la referencia refs/tags/{tag} de Git a la compilación completada. Esto proporciona a su equipo una rastreabilidad adicional y una manera más fácil de navegar desde la compilación hasta el código compilado. La etiqueta se considera un artefacto de compilación, ya que la compilación la genera. Cuando la compilación se elimina manualmente o a través de una directiva de retención, la etiqueta también se elimina.

Preguntas más frecuentes

Los problemas relacionados con la integración de Azure Repos se dividen en tres categorías:

• Desencadenadores con errores: mi canalización no se desencadena cuando inserto una actualización en el repositorio.
• Error de restauración: mi canalización se desencadena, pero se produce un error en el paso de restauración.
• Versión incorrecta: mi canalización se ejecuta, pero usa una versión inesperada del código fuente o YAML.

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.

  

  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.

  

• ¿Está configurando el desencadenador de PR en el archivo YAML o en las directivas de rama del repositorio? No puede configurar un desencadenador de PR en el archivo YAML para un repositorio de Git de Azure Repos. Debe usar directivas de rama.

• ¿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 CI especificados en el archivo YAML.

Tengo varios repositorios en la canalización de YAML. ¿Cómo configuro desencadenadores para cada repositorio?

Consulte desencadenadores en Uso de varios repositorios.

Error en la restauración

Veo el siguiente error en el archivo de registro durante el paso de restauración. ¿Cómo puedo corregirlo?

remote: TF401019: The Git repository with name or identifier XYZ does not exist or you do not have permissions for the operation you are attempting.
fatal: repository 'XYZ' not found
##[error] Git fetch failed with exit code: 128

Siga cada uno de estos pasos para solucionar sus problemas de restauración:

• ¿Sigue existiendo el repositorio? En primer lugar, asegúrese de que lo haga abriéndolo en la página Repositorios.

• ¿Tiene acceso al repositorio mediante un script? Si es así, compruebe la opción Limitar el ámbito de autorización del trabajo a los repositorios de Azure DevOps a los que se hace referencia. Cuando se habilita Limitar el ámbito de autorización del trabajo a los repositorios de Azure DevOps a los que se hace referencia, no podrá restaurar los repositorios de Git de Azure Repos mediante un script a menos que se haga referencia explícitamente primero en la canalización.

• ¿Cuál es el ámbito de autorización del trabajo de la canalización?

  • Si el ámbito es la colección:

    • Podría ser un error intermitente. Vuelva a ejecutar la canalización.
    • Es posible que alguien haya quitado el acceso a la cuenta del servicio de compilación de recopilación de proyectos.
      • Vaya a Configuración del proyecto para el proyecto en el que existe el repositorio. Seleccione Repositorios>Repos>, repositorios específicos y, después, Seguridad.
      • Compruebe si el servicio de compilación de recopilación de proyectos (nombre de su colección) existe en la lista de usuarios.
      • Compruebe si esa cuenta tiene la etiqueta Crear y el acceso de lectura.

  • Si el ámbito es proyecto:

    • ¿El repositorio está en el mismo proyecto que la canalización?
      • Sí:
        • Podría ser un error intermitente. Vuelva a ejecutar la canalización.
        • Es posible que alguien haya quitado el acceso a la cuenta del servicio de compilación de proyectos.
          • Vaya a Configuración del proyecto para el proyecto en el que existe el repositorio. Seleccione Repositorios>Repos>, repositorios específicos y, después, Seguridad.
          • Compruebe si el servicio de compilación de su nombre del proyecto (nombre de su colección) existe en la lista de usuarios.
          • Compruebe si esa cuenta tiene la etiqueta Crear y el acceso de lectura.
      • No:
        • ¿La canalización está en un proyecto público?
          • Sí: No se puede acceder a los recursos fuera del proyecto público. Haga que el proyecto sea privado.
          • No: debe configurar los permisos para acceder a otro repositorio de la misma colección de proyectos.

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 PR, el archivo YAML resultante de combinar las ramas de origen y destino del PR se evalúa para ver si se debe ejecutar una compilación de PR.

Artículos relacionados

• Desencadenadores programados
• Desencadenadores de finalización de canalización