Variables clásicas de versión y de artefacto
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Las variables clásicas de versión y artefactos son una manera cómoda de intercambiar y transportar datos a lo largo de la canalización. Cada variable se almacena como una cadena y su valor puede cambiar entre ejecuciones de la canalización.
Las variables son diferentes de los parámetros en tiempo de ejecución que solo están disponibles en el tiempo de análisis de plantillas.
A medida que redacte las tareas para implementar la aplicación en cada fase de los procesos de CI/CD de DevOps, las variables le ayudarán a:
Definir una canalización de implementación más genérica una vez y personalizarla fácilmente para cada fase. Por ejemplo, se puede usar una variable para representar la cadena de conexión para la implementación web y el valor de esta variable se puede cambiar de una fase a otra. Estas son variables personalizadas.
Use información sobre el contexto de la versión, fase, artefactos o agente concretos en el que se está ejecutando la canalización de implementación. Por ejemplo, el script puede necesitar acceso a la ubicación de la compilación para descargarla o al directorio de trabajo del agente para crear archivos temporales. Estas son variables predeterminadas.
Nota:
Para las canalizaciones de YAML, consulte variables definidas por el usuario y variables predefinidas para obtener más detalles.
Variables predeterminadas
La información sobre el contexto de ejecución está disponible para ejecutar tareas a través de variables predeterminadas. Las tareas y scripts pueden usar esas variables para encontrar información sobre el sistema, la versión, la fase o el agente en los que se ejecutan. Con la excepción de System.Debug, estas variables son de solo lectura y el sistema establece automáticamente sus valores. Algunas de las variables más significativas se describen en las tablas siguientes. Para ver la lista completa, consulte Ver los valores actuales de todas las variables.
Sugerencia
Puede ver los valores actuales de todas las variables de una versión y usar una variable predeterminada para ejecutar una versión en modo de depuración.
Sistema
Nombre de la variable | Descripción |
---|---|
System.TeamFoundationServerUri | La URL de la conexión de servicio en Azure Pipelines. Use esto a partir de los scripts o tareas para llamar a las API de REST de Azure Pipelines. Ejemplo: https://fabrikam.vsrm.visualstudio.com/ |
System.TeamFoundationCollectionUri | Dirección URL de la colección de Team Foundation o Azure Pipelines. Use esto a partir de los scripts o tareas para llamar a las API de REST en otros servicios, como Compilación y Control de versiones. Ejemplo: https://dev.azure.com/fabrikam/ |
System.CollectionId | Identificador de la colección a la que pertenece esta compilación o versión. Ejemplo: 6c6f3423-1c84-4625-995a-f7f143a1e43d |
System.DefinitionId | Id. de la canalización de versión a la que pertenece la versión actual. Ejemplo: 1 |
System.TeamProject | Nombre del proyecto al que pertenece la compilación o versión. Ejemplo: Fabrikam |
System.TeamProjectId | Id. del proyecto al que pertenece la compilación o versión. Ejemplo: 79f5c12e-3337-4151-be41-a268d2c73344 |
System.ArtifactsDirectory | Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que Agent.ReleaseDirectory y System.DefaultWorkingDirectory. Ejemplo: C:\agent\_work\r1\a |
System.DefaultWorkingDirectory | Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que Agent.ReleaseDirectory y System.ArtifactsDirectory. Ejemplo: C:\agent\_work\r1\a |
System.WorkFolder | Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.RootDirectory y Agent.WorkFolder. Ejemplo: C:\agent\_work |
System.Debug | Esta es la única variable del sistema que los usuarios pueden establecer. Establézcalo en true para ejecutar la versión en modo de depuración para ayudar en la búsqueda de errores. Ejemplo: true |
Release
Nombre de la variable | Descripción |
---|---|
Release.AttemptNumber | Número de veces que esta versión se implementa en esta fase. Ejemplo: 1 |
Release.DefinitionEnvironmentId | Identificador de la fase en la canalización de versión correspondiente. Ejemplo: 1 |
Release.DefinitionId | Id. de la canalización de versión a la que pertenece la versión actual. Ejemplo: 1 |
Release.DefinitionName | Nombre de la canalización de versión a la que pertenece la versión actual. Ejemplo: fabrikam-cd |
Release.Deployment.RequestedFor | Nombre para mostrar de la identidad que desencadenó (iniciado) la implementación actualmente en curso. Ejemplo: Mateo Escobedo |
Release.Deployment.RequestedForEmail | Dirección de correo electrónico de la identidad que desencadenó (iniciado) la implementación actualmente en curso. Ejemplo: mateo@fabrikam.com |
Release.Deployment.RequestedForId | Id. de la identidad que desencadenó (iniciado) la implementación actualmente en curso. Ejemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.DeploymentID | Identificador de la implementación. Único por trabajo. Ejemplo: 254 |
Release.DeployPhaseID | Identificador de la fase en la que se ejecuta la implementación. Ejemplo: 127 |
Release.EnvironmentId | Identificador de la instancia de fase en una versión en la que la implementación está actualmente en proceso. Ejemplo: 276 |
Release.EnvironmentName | Nombre de la fase en la que la implementación está actualmente en curso. Ejemplo: Dev |
Release.EnvironmentUri | URI de la instancia de fase en una versión en la que la implementación está actualmente en proceso. Ejemplo: vstfs://ReleaseManagement/Environment/276 |
Release.Environments.{stage-name}.status | El estado de la implementación de la fase. Ejemplo: InProgress |
Release.PrimaryArtifactSourceAlias | Alias del origen del artefacto principal Ejemplo: fabrikam\_web |
Release.Reason | Motivo de la implementación. Los valores admitidos son:ContinuousIntegration : la versión se inició en la implementación continua después de completar una compilación.Manual : la versión se inició manualmente.None : no se ha especificado el motivo de implementación.Schedule : la versión iniciada a partir de una programación. |
Release.ReleaseDescription | Descripción del texto proporcionada en el momento de la versión. Ejemplo: Critical security patch |
Release.ReleaseId | Identificador del registro de versión actual. Ejemplo: 118 |
Release.ReleaseName | El nombre de la versión actual. Ejemplo: Release-47 |
Release.ReleaseUri | URI de la versión actual. Ejemplo: vstfs://ReleaseManagement/Release/118 |
Release.ReleaseWebURL | Dirección URL de esta versión. Ejemplo: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary |
Release.RequestedFor | Nombre para mostrar de la identidad que desencadenó la versión. Ejemplo: Mateo Escobedo |
Release.RequestedForEmail | Dirección de correo electrónico de la identidad que desencadenó la versión. Ejemplo: mateo@fabrikam.com |
Release.RequestedForId | Id. de la identidad que desencadenó la versión. Ejemplo: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.SkipArtifactsDownload | Valor booleano que especifica si se va a omitir la descarga de artefactos en el agente. Ejemplo: FALSE |
Release.TriggeringArtifact.Alias | Alias del artefacto que desencadenó la versión. Esto estaba vacío cuando la versión se programó o desencadenó manualmente. Ejemplo: fabrikam\_app |
Fase de versión
Nombre de la variable | Descripción |
---|---|
Release.Environments.{stage-name}.Status | Estado de la implementación de esta versión dentro de una fase especificada. Ejemplo: NotStarted |
Agente
Nombre de la variable | Descripción |
---|---|
Agent.Name | Nombre del agente registrado con el grupo de agentes. Es probable que esto sea diferente del nombre del equipo. Ejemplo: fabrikam-agent |
Agent.MachineName | Nombre del equipo en el que se configura el agente. Ejemplo: fabrikam-agent |
Agent.Version | Versión del software del agente. Ejemplo: 2.109.1 |
Agent.JobName | Nombre del trabajo que se está ejecutando, como Versión o Compilación. Ejemplo: Release |
Agent.HomeDirectory | Carpeta donde está instalado el agente. Esta carpeta contiene el código y los recursos del agente. Ejemplo: C:\agent |
Agent.ReleaseDirectory | Directorio en el que se descargan los artefactos durante la implementación de una versión. El directorio se borra antes de cada implementación si requiere que los artefactos se descarguen en el agente. Igual que System.ArtifactsDirectory y System.DefaultWorkingDirectory. Ejemplo: C:\agent\_work\r1\a |
Agent.RootDirectory | Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.WorkFolder y System.WorkFolder. Ejemplo: C:\agent\_work |
Agent.WorkFolder | Directorio de trabajo para este agente, donde se crean subcarpetas para cada compilación o versión. Igual que Agent.RootDirectory y System.WorkFolder. Ejemplo: C:\agent\_work |
Agent.DeploymentGroupId | Identificador del grupo de implementación con el que está registrado el agente. Esto solo está disponible en los trabajos del grupo de implementación. Ejemplo: 1 |
Artefacto general
Para cada artefacto al que se hace referencia en una versión, puede usar las siguientes variables de artefacto. No todas las variables son significativas para cada tipo de artefacto. En la tabla siguiente se enumeran las variables de artefacto predeterminadas y se proporcionan ejemplos de los valores que tienen en función del tipo de artefacto. Si un ejemplo está vacío, implica que la variable no se rellena para ese tipo de artefacto.
Reemplace el marcador de posición {alias}
por el valor especificado para el alias de artefacto o por el valor predeterminado generado para la canalización de versión.
Nombre de la variable | Descripción |
---|---|
Release.Artifacts.{alias}.DefinitionId | Identificador de la canalización de compilación o del repositorio. Ejemplo de Azure Pipelines: 1 Ejemplo de GitHub: fabrikam/asp |
Release.Artifacts.{alias}.DefinitionName | Nombre de la canalización de compilación o del repositorio. Ejemplo de Azure Pipelines: fabrikam-ci Ejemplo de TFVC: $/fabrikam Ejemplo de Git: fabrikam Ejemplo de GitHub: fabrikam/asp (main) |
Release.Artifacts.{alias}.BuildNumber | Número de compilación o identificador de confirmación. Ejemplo de Azure Pipelines: 20170112.1 Ejemplo de Jenkins/TeamCity: 20170112.1 Ejemplo de TFVC: Changeset 3 Ejemplo de Git: 38629c964 Ejemplo de GitHub: 38629c964 |
Release.Artifacts.{alias}.BuildId | Identificador de compilación. Ejemplo de Azure Pipelines: 130 Ejemplo de Jenkins/TeamCity: 130 Ejemplo de GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
Release.Artifacts.{alias}.BuildURI | Dirección URL de la compilación. Ejemplo de Azure Pipelines: vstfs://build-release/Build/130 Ejemplo de GitHub: https://github.com/fabrikam/asp |
Release.Artifacts.{alias}.SourceBranch | Ruta de acceso completa y nombre de la rama desde la que se creó el origen. Ejemplo de Azure Pipelines: refs/heads/main |
Release.Artifacts.{alias}.SourceBranchName | El nombre solo de la rama desde la que se creó el origen. Ejemplo de Azure Pipelines: main |
Release.Artifacts.{alias}.SourceVersion | Confirmación que se ha compilado. Ejemplo de Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7 |
Release.Artifacts.{alias}.Repository.Provider | Tipo de repositorio desde el que se creó el origen. Ejemplo de Azure Pipelines: Git |
Release.Artifacts.{alias}.RequestedForID | Identificador de la cuenta que desencadenó la compilación. Ejemplo de Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
Release.Artifacts.{alias}.RequestedFor | Nombre de la cuenta que solicitó la compilación. Ejemplo de Azure Pipelines: Mateo Escobedo |
Release.Artifacts.{alias}.Type | El tipo de origen del artefacto, como Build. Ejemplo de Azure Pipelines: Build Ejemplo de Jenkins: Jenkins Ejemplo de TeamCity: TeamCity Ejemplo de TFVC: TFVC Ejemplo de Git: Git Ejemplo de GitHub: GitHub |
Release.Artifacts.{alias}.PullRequest.TargetBranch | Ruta de acceso completa y nombre de la rama que es el destino de una solicitud de una incorporación de cambios. Esta variable solo se inicializa si un flujo de solicitud de incorporación de cambios desencadena la versión. Ejemplo de Azure Pipelines: refs/heads/main |
Release.Artifacts.{alias}.PullRequest.TargetBranchName | Solo el nombre de la rama que es el destino de una solicitud de incorporación de cambios. Esta variable solo se inicializa si un flujo de solicitud de incorporación de cambios desencadena la versión. Ejemplo de Azure Pipelines: main |
Consulte también Alias de origen del artefacto.
Artefacto principal
Designe uno de los artefactos como artefacto principal en una canalización de versión. Para el artefacto principal designado, Azure Pipelines rellena las siguientes variables.
Nombre de la variable | Igual que |
---|---|
Build.DefinitionId | Release.Artifacts.{Primary artifact alias}.DefinitionId |
Build.DefinitionName | Release.Artifacts.{Primary artifact alias}.DefinitionName |
Build.BuildNumber | Release.Artifacts.{Primary artifact alias}.BuildNumber |
Build.BuildId | Release.Artifacts.{Primary artifact alias}.BuildId |
Build.BuildURI | Release.Artifacts.{Primary artifact alias}.BuildURI |
Build.SourceBranch | Release.Artifacts.{Primary artifact alias}.SourceBranch |
Build.SourceBranchName | Release.Artifacts.{Primary artifact alias}.SourceBranchName |
Build.SourceVersion | Release.Artifacts.{Primary artifact alias}.SourceVersion |
Build.Repository.Provider | Release.Artifacts.{Primary artifact alias}.Repository.Provider |
Build.RequestedForID | Release.Artifacts.{Primary artifact alias}.RequestedForID |
Build.RequestedFor | Release.Artifacts.{Primary artifact alias}.RequestedFor |
Build.Type | Release.Artifacts.{Primary artifact alias}.Type |
Build.PullRequest.TargetBranch | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch |
Build.PullRequest.TargetBranchName | Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName |
Usar variables predeterminadas
Puede usar las variables predeterminadas de dos maneras: como parámetros para las tareas de una canalización de versión o en los scripts.
Puede usar directamente una variable predeterminada como entrada para una tarea.
Por ejemplo, para pasar Release.Artifacts.{Artifact alias}.DefinitionName
para el origen del artefacto cuyo alias es ASPNET4.CI a una tarea, usaría $(Release.Artifacts.ASPNET4.CI.DefinitionName)
.
Para usar una variable predeterminada en el script, primero debe reemplazar .
en los nombres de variable predeterminados por _
.
Por ejemplo, para imprimir el valor de la variable de artefacto Release.Artifacts.{Artifact alias}.DefinitionName
para el origen del artefacto cuyo alias es ASPNET4.CI en un script de PowerShell, usaría $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME
.
Tenga en cuenta que el nombre original del alias de origen del artefacto, ASPNET4.CI
, se reemplaza por ASPNET4_CI
.
Ver los valores actuales de todas las variables
Abra la vista de canalizaciones del resumen de la versión y elija la fase en la que está interesado. En la lista de pasos, elija Inicializar trabajo.
Se abrirá el registro de este paso. Desplácese hacia abajo para ver los valores usados por el agente para este trabajo.
Ejecución de una versión en modo de depuración
Mostrar información adicional mientras una versión se ejecuta y en los archivos de registro ejecutando toda la versión, o simplemente las tareas en una fase de versión individual, en modo de depuración. Esto puede ayudarle a resolver problemas y errores.
Para iniciar el modo de depuración para una versión completa, agregue una variable denominada
System.Debug
con el valortrue
a la pestaña Variables de una canalización de versión.Para iniciar el modo de depuración para una sola fase, abra el cuadro de diálogo Configurar fase desde el menú contextual de la fase y agregue una variable denominada
System.Debug
con el valortrue
a la pestaña Variables.Como alternativa, cree un grupo de variables que contenga una variable denominada
System.Debug
con el valortrue
y vincule este grupo de variables a una canalización de versión.
Sugerencia
Si recibe un error relacionado con una conexión de servicio de Azure RM, consulte Solución de problemas de conexiones de servicio de Azure Resource Manager.
Variables personalizadas
Las variables personalizadas se pueden definir en varios ámbitos.
Comparta valores entre todas las definiciones de un proyecto mediante grupos de variables. Elija un grupo de variables cuando necesite usar los mismos valores en todas las definiciones, fases y tareas de un proyecto, y desea poder cambiar los valores en un solo lugar. Puede definir y administrar grupos de variables en la pestaña Biblioteca.
Comparta valores en todas las fases mediante variables de canalización de versión. Elija una variable de canalización de versión cuando necesite usar el mismo valor en todas las fases y tareas de la canalización de versión y desee cambiar el valor en un solo lugar. Puede definir y administrar estas variables en la pestaña Variables de una canalización de versión. En la página Variables de canalización, abra la lista desplegable Ámbito y seleccione "Release". De forma predeterminada, cuando se agrega una variable, se establece en Ámbito de versión.
Comparta valores entre todas las tareas dentro de una fase específica mediante variables de fase. Use una variable de nivel de fase para los valores que varían de una fase a otra (y son iguales para todas las tareas de una fase). Puede definir y administrar estas variables en la pestaña Variables de una canalización de versión. En la página Variables de canalización, abra la lista desplegable Ámbito y seleccione la fase necesaria. Al agregar una variable, establezca el ámbito en el entorno adecuado.
El uso de variables personalizadas en el ámbito de proyecto, canalización de versión y fase le ayuda a:
Evite la duplicación de valores, lo que facilita la actualización de todas las repeticiones como una operación.
Almacene valores confidenciales de forma que los usuarios de las canalizaciones de versión no puedan ver ni cambiarlos. Designe una propiedad de configuración para que sea una variable segura (secreta) seleccionando el (candado) situado junto a la variable.
Importante
Los valores de las variables ocultas (secretas) se almacenan de forma segura en el servidor y los usuarios no pueden verlos después de guardarlas. Durante una implementación, el servicio de versión de Azure Pipelines descifra estos valores cuando las tareas hacen referencia a ellos y los pasa al agente a través de un canal HTTPS seguro.
Nota:
La creación de variables personalizadas puede sobrescribir variables estándar. Por ejemplo, la variable de entorno Ruta de acceso de PowerShell. Si crea una variable personalizada Path
en un agente de Windows, sobrescribirá la variable $env:Path
y PowerShell no podrá ejecutarse.
Uso de variables personalizadas
Para usar variables personalizadas en las tareas de compilación y versión, basta con incluir el nombre de la variable entre paréntesis y precederlo con un carácter $. Por ejemplo, si tiene una variable denominada adminUserName, puede insertar el valor actual de esa variable en un parámetro de una tarea como $(adminUserName)
.
Nota:
Las variables de distintos grupos vinculados a una canalización en el mismo ámbito (por ejemplo, trabajo o fase) colisionarán y el resultado puede ser impredecible. Asegúrese de usar nombres diferentes para las variables en todos los grupos de variables.
Definición y modificación de las variables en un script
Para definir o modificar una variable a partir de un script, use el comando de registro task.setvariable
.
El valor de variable actualizado tiene como ámbito el trabajo que se ejecuta y no fluye entre trabajos o fases.
Los nombres de variable se transforman en mayúsculas y los caracteres "." y " " se reemplazan por "_".
Por ejemplo, Agent.WorkFolder
se convierte en AGENT_WORKFOLDER
.
En Windows, puede acceder a esta variable como %AGENT_WORKFOLDER%
o $env:AGENT_WORKFOLDER
.
En Linux y macOS, use $AGENT_WORKFOLDER
.
Sugerencia
Puede ejecutar un script en:
- Agente de Windows mediante una tarea de script de Batch o una tarea de script de PowerShell.
- Agente de macOS o Linux mediante una tarea de script de Shell.
Script de Batch
Establecer las variables sauce
y secret.Sauce
@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic
Leer las variables
Argumentos
"$(sauce)" "$(secret.Sauce)"
Script
@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)
Salida de la consola de la lectura de las variables:
No problem reading crushed tomatoes or crushed tomatoes
But I cannot read
But I can read ******** (but the log is redacted so I do not spoil the secret)