Uso seguro de variables y parámetros en la canalización

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Aprenda a usar variables y parámetros de forma segura para recopilar entradas de los usuarios de canalización. Vea los siguientes artículos para más información:

• Definición de variables
• Establecimiento de variables secretas
• Usar variables predefinidas
• Usar parámetros en tiempo de ejecución
• Uso de tipos de plantilla

Tenga cuidado con las variables secretas. Los métodos recomendados para establecer variables secretas incluyen el uso de la interfaz de usuario, la creación de un grupo de variables o el uso de un grupo de variables de origen de Azure Key Vault. Para más información, consulte configurar variables de entorno.

Variables

Las variables sirven como un método práctico para recopilar la entrada inicial del usuario y facilitar la transferencia de datos entre los pasos de la canalización. Sin embargo, tenga cuidado al trabajar con variables. De forma predeterminada, las variables recién creadas, ya sean definidas en YAML o con scripts, son de lectura y escritura. Los pasos de bajada pueden modificar los valores de variable de forma inesperada.

Por ejemplo, considere el siguiente fragmento de código de script:

msbuild.exe myproj.proj -property:Configuration=$(MyConfig)

Si un paso anterior establece en MyConfig Debug & deltree /y c:, podría dar lugar a consecuencias no deseadas. Aunque este ejemplo simplemente elimina el contenido del agente de compilación, resalta el peligro potencial de dicha configuración.

Puede hacer que las variables sean de solo lectura. Las variables del sistema, como Build.SourcesDirectory, las variables de salida de tareas y las variables en tiempo de cola siempre son de solo lectura. Las variables creadas en YAML o creadas en tiempo de ejecución por un script se pueden designar como de solo lectura. Cuando un script o una tarea crea una variable, puede pasar la marca isReadonly=true en su comando de registro para que la variable sea de solo lectura.

En YAML, puede especificar variables de solo lectura mediante la siguiente clave específica:

variables:
- name: myReadOnlyVar
  value: myValue
  readonly: true

Variables de tiempo en cola

Al definir una variable en el editor de la interfaz de usuario de Pipelines, puede permitir que los usuarios invaliden su valor durante la ejecución de la canalización. Estas variables se conocen como variables en tiempo de cola y siempre se definen en el editor de la interfaz de usuario de Pipelines.

Las variables en tiempo de cola se exponen al usuario final cuando ejecutan manualmente una canalización y pueden cambiar sus valores.

Los usuarios necesitan el permiso Editar configuración de compilación de colas en la canalización para especificar variables establecidas en tiempo de cola.

Limitar las variables que pueden establecerse en el momento de la puesta en cola.

La interfaz de usuario y la API REST usadas para ejecutar una canalización ofrecen medios para que los usuarios definan nuevas variables en tiempo de cola.

En los primeros días de Azure Pipelines, esta funcionalidad tenía los siguientes problemas:

• Permite a los usuarios definir nuevas variables no definidas por el autor de la canalización en la definición.
• Permitía a los usuarios invalidar las variables del sistema.

Para solucionar estos problemas, definimos una configuración para limitar las variables que se pueden establecer en tiempo de cola. Con esta configuración activada, solo se pueden establecer las variables marcadas explícitamente como "Settable at queue time". En otras palabras, puede establecer cualquier variable en tiempo de cola a menos que esta configuración esté activada.

La configuración está diseñada para funcionar en los niveles de organización y proyecto.

• Nivel de organización:
  • Cuando la configuración está activada, aplica que solo las variables marcadas explícitamente como "Settable at queue time" se pueden modificar para todas las canalizaciones de todos los proyectos de la organización.
  • Los administradores de la colección de proyectos pueden habilitar o deshabilitar esta configuración.
  • Acceda a esta configuración en Configuración de la organización Pipelines Settings (Configuración>de canalizaciones).>
• Nivel de proyecto:
  • De forma similar al nivel de organización, habilitar esta configuración garantiza que solo se puedan modificar las variables marcadas como "Settable at queue time" para todas las canalizaciones del proyecto específico.
  • Si la configuración de nivel de organización está habilitada, se aplica a todos los proyectos y no se puede desactivar.
  • Los administradores del proyecto pueden habilitar o deshabilitar esta configuración.
  • Acceda a esta configuración en Configuración del proyecto Pipelines Settings (Configuración de canalizaciones>de project).>

En el ejemplo siguiente se muestra que la configuración está activada y la canalización define una variable denominada my_variable que no se puede establecer en el momento de la cola.

A continuación, supongamos que desea ejecutar la canalización. El panel Variables no muestra ninguna variable y falta el botón Agregar variable.

El uso de compilaciones : cola y ejecuciones: ejecutar llamadas a la API REST de canalización para poner en cola una ejecución de canalización y establecer el valor de my_variable o de una nueva variable produce un error similar al siguiente.

{
  "$id": "1",
  "innerException": null,
  "message": "You can't set the following variables (my_variable). If you want to be able to set these variables, then edit the pipeline and select Settable at queue time on the variables tab of the pipeline editor.",
  "typeName": "Microsoft.Azure.Pipelines.WebApi.PipelineValidationException, Microsoft.Azure.Pipelines.WebApi",
  "typeKey": "PipelineValidationException",
  "errorCode": 0,
  "eventId": 3000
}

Parámetros

A diferencia de las variables, una canalización en ejecución no puede modificar parámetros de canalización. Los parámetros tienen tipos de datos como number y string, y se pueden restringir a subconjuntos de valores específicos. Esta restricción es valiosa cuando un aspecto configurable por el usuario de la canalización solo debe aceptar valores de una lista predefinida, lo que garantiza que la canalización no acepta datos arbitrarios.

Habilitar la validación de parámetros de argumentos de tareas de shell

Las canalizaciones pueden hacer referencia a las tareas ejecutadas dentro de la canalización. Algunas tareas incluyen un arguments parámetro que permite especificar más opciones para la tarea.

Cuando la opción Habilitar validación de parámetros de argumentos de tareas de shell está habilitada, el parámetro arguments se somete a revisión para asegurarse de que el shell ejecuta correctamente caracteres como punto y coma, comillas y paréntesis. De forma similar a la opción Limitar variables que se pueden establecer en tiempo de cola, puede configurar Habilitar validación de parámetros de argumentos de tareas de shell en el nivel de organización o proyecto en Configuración de canalizaciones>de configuración.>

Cuando esta característica está activada, los problemas de validación relacionados con el arguments parámetro desencadenan un mensaje de error como el siguiente:

Detected characters in arguments that may not be executed correctly by the shell. Please escape special characters using backtick (`).

Para resolver este problema, ajuste los argumentos mediante el escape de caracteres especiales como se indica en el mensaje de error. Esta validación se aplica al arguments parámetro en las siguientes tareas específicas:

• PowerShell
• BatchScript
• Bash
• Ssh
• AzureFileCopy
• WindowsMachineFileCopy

Pasos siguientes

Protección de la infraestructura compartida