Compartir vía

Opciones de canalización para repositorios GIT

  • Artículo

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

Al editar una canalización que usa un repositorio de Git (en un proyecto de Azure DevOps, GitHub, GitHub Enterprise Server, Bitbucket Cloud u otro repositorio de Git), tiene las siguientes opciones.

Característica Azure Pipelines Azure DevOps Server 2019 y versiones posteriores TFS 2018
Rama Sí Sí Sí
Clean Sí Sí Sí
Etiquetas u orígenes de etiquetas Proyecto; solo clásico Proyecto de equipo Proyecto de equipo
Notificar estado de la compilación Sí Sí Sí
Extraer submódulos Sí Sí Sí
Extraer archivos de LFS Sí Sí Sí
Clonar un segundo repositorio Sí Sí Sí
No sincronizar orígenes Sí Sí Sí
Recuperar cambios superficiales Sí Sí Sí

Nota

Haga clic en Configuración avanzada en la tarea Obtener orígenes para ver algunas de estas opciones.

Rama

Esta es la rama que desea que sea la predeterminada al poner manualmente en cola esta compilación. Si establece un desencadenador programado para la compilación, se trata de la rama desde la que la compilación obtendrá los orígenes más recientes. La rama predeterminada no tiene efecto cuando la compilación se desencadena mediante integración continua (CI). Normalmente, se establecerá para que sea la misma que la rama predeterminada del repositorio (por ejemplo, "master").

Limpieza del repositorio local en el agente

Puede limpiar el directorio de trabajo del agente autohospedado de distintas formas 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. Al usar agentes autohospedados, en función de cómo se configuran los grupos de agentes, puede obtener un nuevo agente para ejecuciones de canalización posteriores (o fases o trabajos en la misma canalización), por lo que no es una garantía de que las ejecuciones, trabajos o fases posteriores puedan acceder a las salidas de ejecuciones, trabajos o fases anteriores.

Nota:

Al usar agentes autohospedados, en función de cómo se configuran los grupos de agentes, puede obtener un nuevo agente para ejecuciones de canalización posteriores (o fases o trabajos en la misma canalización), por lo que no es una garantía de que las ejecuciones, trabajos o fases posteriores puedan acceder a las salidas de ejecuciones, trabajos o fases anteriores. Puede usar artefactos de compilación para compartir las salidas de una ejecución de canalización, una fase o un trabajo con ejecuciones, fases o trabajos posteriores.

Azure Pipelines, Azure DevOps Server 2019 y versiones posteriores

Hay varias opciones de limpieza disponibles para las canalizaciones de YAML.

  • El paso checkout tiene una opción clean. Cuando se establece en true, la canalización ejecuta execute git clean -ffdx && git reset --hard HEAD antes de capturar el repositorio. Para más información, consulte Extracción.
  • La configuración de workspace para job tiene varias opciones de limpieza (salidas, recursos, todo). Para más información, consulte Área de trabajo.
  • La interfaz de usuario de configuración de la canalización tiene una configuración Limpiar que, cuando se establece en true, es equivalente a especificar clean: true para cada paso checkout de la canalización. Para configurar la opción Limpiar:

    1. Edite la canalización, elija ... y seleccione Desencadenadores.

      Editar desencadenadores.

    2. Seleccione YAML, Obtener orígenes y configure la opción de Limpiar deseada. El valor predeterminado es true.

      Configuración de la limpieza.

Para invalidar la configuración de la limpieza al ejecutar manualmente una canalización, puede usar parámetros en tiempo de ejecución. En el ejemplo siguiente, se usa un parámetro en tiempo de ejecución para configurar las opciones de limpieza de la extracción.

parameters:
- name: clean
  displayName: Checkout clean
  type: boolean
  default: true
  values:
  - false
  - true

trigger:
- main

pool: FabrikamPool
#  vmImage: 'ubuntu-latest'

steps:
- checkout: self
  clean: ${{ parameters.clean }}

De forma predeterminada, se establece clean en true, pero se puede invalidar al ejecutar manualmente la canalización; para ello, desactive la casilla Limpieza extracción que se agrega para el parámetro en tiempo de ejecució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 las correctas.

Nota:

Esta característica solo se puede usar cuando el repositorio de origen de la compilación es un repositorio de GitHub o un repositorio de Git o TFVC del proyecto.

En el formato Etiqueta, puede usar variables definidas por el usuario y predefinidas con ámbito "Todo". 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 mediante una directiva de retención, la etiqueta también se elimina.

Estado de compilación del informe (Azure Pipelines, TFS 2018 y versiones posteriores)

Tiene la opción de proporcionar al equipo una vista del estado de la compilación desde el repositorio de origen remoto.

Si los orígenes están en un repositorio de Git de Azure Repos en el proyecto, esta opción muestra un distintivo en la página Código que indica si la compilación se está pasando o no. El estado de la compilación se muestra en las pestañas siguientes:

  • Archivos: indica el estado de la implementación más reciente de la rama seleccionada.
  • Confirmaciones: indica el estado de compilación de cada confirmación (esto requiere que el desencadenador de integración continua (CI) esté habilitado para las compilaciones).
  • Ramas: indica el estado de la implementación más reciente de cada rama.

Si usa varias canalizaciones de compilación para el mismo repositorio del proyecto, puede optar por habilitar esta opción para una o varias de las canalizaciones. En el caso de que esta opción esté habilitada en varias canalizaciones, la notificación de la página Código indica el estado de la compilación más reciente en todas las canalizaciones. Los miembros del equipo pueden hacer clic en la notificación de estado de la compilación para ver el estado de la compilación más reciente para cada una de las canalizaciones de compilación.

GitHub

Si los orígenes están en GitHub, esta opción publica el estado de la compilación en GitHub mediante las API de comprobación o estado de GitHub. Si la compilación se desencadena desde una solicitud de incorporación de cambios de GitHub, puede ver el estado en la página de solicitudes de incorporación de cambios de GitHub. Esto también permite establecer directivas de estado en GitHub y automatizar las combinaciones. Si la compilación se desencadena mediante integración continua (CI), puede ver el estado de compilación en la confirmación o rama en GitHub.

Otros tipos de repositorios remotos de Git

Si el origen está en cualquier otro tipo de repositorio remoto, no puede usar Azure Pipelines o TFS para publicar automáticamente el estado de compilación en ese repositorio. Sin embargo, puede usar un distintivo de compilación como manera de integrar y mostrar el estado de compilación dentro de las experiencias de control de versiones.

Ruta de acceso de extracción

Si va a restaurar un único repositorio, de forma predeterminada, el código fuente se restaura en un directorio denominado s. 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 extracció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 acceso de extracción válida (es decir, C:\agent\_work\1\anotherpath), pero un valor como ..\invalidpath, no (es decir, C:\agent\_work\invalidpath).

Si usa varios pasos checkout y restaura varios repositorios, y desea especificar explícitamente la carpeta mediante path, considere la posibilidad de evitar la configuración de la ruta de acceso que sea la subcarpeta de otra ruta de acceso del paso de extracción (es decir, C:\agent\_work\1\s\repo1 y C:\agent\_work\1\s\repo1\repo2); de lo contrario, la limpieza de otro repositorio borrará la subcarpeta del paso de extracción. Tenga en cuenta que este caso es válido si la opción de limpieza es true para repo1.

Nota:

La ruta de acceso de extracción solo se puede especificar para las canalizaciones YAML. Para más información, consulte Extracción en el esquema YAML.

Extraer submódulos

Seleccione si desea descargar archivos de submódulos. Puede elegir obtener los submódulos inmediatos o todos los submódulos anidados a cualquier profundidad de recursividad. Si desea usar LFS con submódulos, asegúrese de consultar la nota sobre el uso de LFS con submódulos.

Nota:

Para más información sobre la sintaxis de YAML para restaurar submódulos, consulte Restauración en el esquema YAML.

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:

    • se incluye en el mismo proyecto, organización de GitHub o cuenta de Bitbucket Cloud que el repositorio de Git especificado anteriormente.

    • Se agrega mediante una dirección URL relativa al repositorio principal. Por ejemplo, se restaurará este: git submodule add /../../submodule.git mymodule Este no se restaurará: git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule

Submódulos autenticados

Nota:

Asegúrese de que ha registrado los submódulos mediante HTTPS y no SSH.

Para obtener los orígenes de los submódulos se usan las mismas credenciales que usa el agente para obtener los orígenes del repositorio principal.

Si el repositorio principal y los submódulos están en un repositorio de Git Azure Repos en el proyecto de Azure DevOps, puede seleccionar la cuenta que se usa para acceder a los orígenes. En la pestaña Opciones, en el menú Ámbito de autorización del trabajo de compilación, seleccione:

  • Colección de proyectos para usar la cuenta del servicio de compilación de la colección de proyectos

  • Proyecto actual para usar la cuenta del servicio de compilación del proyecto.

Asegúrese de que la cuenta que use tenga acceso tanto al repositorio principal como a los submódulos.

Si el repositorio principal y los submódulos están en la misma organización de GitHub, se usa para acceder a los orígenes el token almacenado en la conexión de servicio de GitHub.

Alternativa al uso de la opción Extraer 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 submódulos no se almacenan en la misma organización de Azure DevOps o en el mismo servicio Git.

Si no puede usar la opción Extraer submódulos, puede usar un paso de script personalizado para capturar 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_TOKEN_DESCRIBED_ABOVE>" submodule update --init --recursive

Asegúrese de reemplazar "<BASIC_AUTH_TOKEN>" por el token codificado 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 ha generado. 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 el usuario no puede interactuar.

Extraer archivos de LFS

Selecciónelo si desea descargar archivos de almacenamiento de archivos grandes (LFS).

En el editor clásico, active la casilla para habilitar esta opción.

En una compilación de YAML, agregue un paso de extracción con lfs establecido en true:

steps:
- checkout: self
  lfs: true

Si usa TFS o si usa Azure Pipelines con un agente autohospedado, debe instalar git-lfs en el agente para que esta opción funcione. Si los agentes hospedados usan Windows, considere la posibilidad de usar la variable System.PreferGitFromPath para asegurarse de que las canalizaciones usan las versiones de git y git-lfs que ha instalado en la máquina. Para más información, consulte ¿Qué versión de Git ejecuta mi agente?

Uso de Git LFS con submódulos

Si un submódulo contiene archivos LFS, debe configurarse Git LFS antes de que se extraigan los submódulos. Los agentes de macOS y Linux que hospeda Microsoft vienen preconfigurados de esta manera. Es posible que los agentes de Windows y los agentes de macOS/Linux autohospedados no.

Como solución alternativa, si usa YAML, puede agregar el siguiente paso antes de checkout:

steps:
- script: |
    git config --global --add filter.lfs.required true
    git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
    git config --global --add filter.lfs.process "git-lfs filter-process"
    git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
  displayName: Configure LFS for use with submodules
- checkout: self
  lfs: true
  submodules: true
# ... rest of steps ...

Clonar un segundo repositorio

De forma predeterminada, la canalización está asociada a un repositorio de Azure Repos o a un proveedor externo. Este es el repositorio que puede desencadenar compilaciones en las confirmaciones y las solicitudes de incorporación de cambios.

Es posible que quiera incluir orígenes de un segundo repositorio en la canalización. Para ello, escriba un script.

git clone https://github.com/Microsoft/TypeScript.git

Si el repositorio no es público, deberá pasar la autenticación al comando de Git.

Azure Repos

La canalización ya tendrá acceso a otros repositorios de su proyecto y puede clonarlos en la canalización mediante un comando de script, como se muestra en el ejemplo siguiente.

- script: | 
    git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" https://organization@dev.azure.com/project/FabrikamFiber/_git/reponame

Puede clonar varios repositorios en el mismo proyecto que la canalización mediante la extracción de varios repositorios.

Si necesita clonar un repositorio de otro proyecto que no sea público, deberá autenticarse como usuario con acceso a ese proyecto.

Nota:

Use una variable secreta para almacenar las credenciales de forma segura.

Las variables secretas no están disponibles automáticamente para los scripts como variables de entorno. Consulte Variables secretas sobre cómo asignarlas.

Para Azure Repos, puede usar un token de acceso personal con el permiso Código (lectura). Envíelo como campo de contraseña en un encabezado de autorización "Básico" sin nombre de usuario. (En otras palabras, codifique en base64 el valor de :<PAT>, incluidos los dos puntos).

AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master

No sincronizar orígenes

Los trabajos que no son de implementación capturan automáticamente los orígenes. Use esta opción si desea omitir ese comportamiento. Esta opción puede ser útil en los casos en los que desee:

  • Usar Git init, config y fetch con sus propias opciones personalizadas.

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

Si desea deshabilitar la descarga de orígenes:

  • Azure Pipelines, TFS 2018 y versiones más recientes: Haga clic en Configuración avanzada y seleccione No sincronizar orígenes.

Nota:

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

Recuperar cambios superficiales

Seleccione si desea limitar el alcance 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, si ha agregado archivos grandes y los ha eliminado más adelante.

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 pone en cola la compilación, la rama que se va a compilar se resuelve en un identificador de confirmación. A continuación, el agente captura la rama y extrae 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 captura 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 captura superficial.

Después de activar la casilla para habilitar esta opción, en el cuadro Profundidad, especifique el número de confirmaciones.

Sugerencia

La variable Agent.Source.Git.ShallowFetchDepth mencionada a continuación también funciona e invalida los controles de casilla. De este modo, puede modificar la configuración al poner en cola la compilación.

Preferencia de Git desde la ruta de acceso

De forma predeterminada, el agente de Windows usa la versión de Git que se incluye con el software del agente. Microsoft recomienda usar la versión de Git que se incluye con el agente, pero tiene varias opciones para invalidar este comportamiento predeterminado y usar la versión de Git que la máquina del agente haya instalado en la ruta de acceso.

  • Establezca una variable de canalización denominada System.PreferGitFromPath en true en las canalizaciones.
  • En los agentes autohospedados, puede crear un archivo denominado .env en el directorio raíz del agente y agregar una línea System.PreferGitFromPath=true al archivo. Para más información, consulte ¿Cómo se establecen diferentes variables de entorno para cada agente?

Para ver la versión de Git que usa una canalización, puede examinar los registros de un paso checkout de la canalización, como se muestra en el ejemplo siguiente.

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

Esta configuración siempre es true en los agentes que no son de Windows.

Opciones de desencadenador para otros Git

Cuando se especifica un repositorio de Git otro/externo, las compilaciones de CI requieren que el repositorio sea accesible desde Internet. Si el repositorio está detrás de un firewall o proxy, solo funcionarán las compilaciones programadas y manuales.

Preguntas más frecuentes

¿Qué protocolos puede usar el agente de compilación con Git?

El agente admite HTTPS.

El agente aún no admite SSH. Consulte Permitir que la compilación use la autenticación SSH al extraer submódulos de Git.

Utilizo TFS en el entorno local y no veo algunas de estas características. ¿Por qué no?

Algunas de estas características solo están disponibles en Azure Pipelines y todavía no lo están en el entorno local. Algunas características están disponibles en el entorno local si ha actualizado a la versión más reciente de TFS.