Crear un decorador de canalización

Azure DevOps Services | Azure DevOps Server 2022

Los decoradores de canalización permiten agregar pasos al principio y al final de cada trabajo. El proceso de creación de un decorador de canalización es diferente de agregar pasos a una sola definición porque se aplica a todas las canalizaciones de una organización.

Supongamos que su organización requiere ejecutar un analizador de virus en todas las salidas de compilación que se podrían liberar. No es necesario que los autores de canalizaciones recuerden agregar ese paso. Creamos un decorador que inserta automáticamente el paso. Nuestro decorador de canalización inserta una tarea personalizada que realiza el examen de virus al final de cada trabajo de canalización.

1. Agregar contribuciones a una extensión

En el ejemplo siguiente se supone que está familiarizado con los modelos de contribución.

1. Cree una extensión. Una vez creada la extensión, tiene un vss-extension.json archivo.
2. Agregue contribuciones al archivo para nuestro vss-extension.json nuevo decorador de canalización.

vss-extension.json

{
    "manifestVersion": 1,
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.post-job-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml"
            }
        }
    ],
    "files": [
        {
            "path": "my-decorator.yml",
            "addressable": true,
            "contentType": "text/plain"
        }
    ]
}

Opciones de contribución

Echemos un vistazo a las propiedades y a lo que se usan para:

Destinos

En este ejemplo, se usa ms.azure-pipelines-agent-job.post-job-tasks porque queremos ejecutar al final de todos los trabajos de compilación.

Esta extensión contribuye a un decorador de canalización. A continuación, creamos un archivo YAML de plantilla para definir el comportamiento del decorador.

2. Crear un archivo YAML decorador

En las propiedades de la extensión, elegimos el nombre "my-decorator.yml". Cree ese archivo en la raíz de la contribución. Contiene el conjunto de pasos que se van a ejecutar después de cada trabajo. Empezamos con un ejemplo básico y trabajamos hasta la tarea completa.

my-decorator.yml (versión inicial)

steps:
- task: CmdLine@2
  displayName: 'Run my script (injected from decorator)'
  inputs:
    script: dir

3. Instalar el decorador

Para agregar un decorador de canalización a su organización, debe instalar una extensión. Solo las extensiones privadas pueden contribuir a decoradores de canalización. La extensión debe crearse y compartirse con su organización para poder usarla.

Una vez que la extensión se haya compartido con su organización, busque la extensión e instálela.

Guarde el archivo y, a continuación , compile e instale la extensión. Cree y ejecute una canalización básica. El decorador inserta automáticamente nuestro dir script al final de cada trabajo. Una ejecución de canalización es similar al ejemplo siguiente.

4. Inyección de condiciones

En nuestro ejemplo, solo es necesario ejecutar el detector de virus si es posible que las salidas de compilación se publiquen al público. Supongamos que solo se publican compilaciones a partir de la rama predeterminada (normalmente main). Debemos limitar el decorador a los trabajos que se ejecutan en la rama predeterminada.

El archivo actualizado tiene este aspecto:

my-decorator.yml (versión revisada)

steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

Puede empezar a ver la potencia de este punto de extensibilidad. Use el contexto del trabajo actual para insertar condicionalmente los pasos en tiempo de ejecución. Use expresiones YAML para tomar decisiones sobre los pasos que se deben insertar y cuándo. Consulte contexto de expresión del decorador de canalización para obtener una lista completa de los datos disponibles.

Hay otra condición que debemos tener en cuenta: ¿qué ocurre si el usuario ya ha incluido el paso de detección de virus? No deberíamos perder tiempo ejecutándolo de nuevo. En este ejemplo sencillo, se pretenderá que cualquier script tarea que se encuentre en el trabajo ejecute el detector de virus. (En una implementación real, tendría una tarea personalizada para comprobarlo en su lugar).

El identificador de la tarea de script es d9bafed4-0b18-4f58-968d-86655b4d2ce9. Si vemos otra tarea de script, no deberíamos insertar la nuestra.

my-decorator.yml (versión final)

steps:
- ${{ if and(eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch), not(containsValue(job.steps.*.task.id, 'd9bafed4-0b18-4f58-968d-86655b4d2ce9'))) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

5. Especificar una tarea de destino

Puede especificar el identificador de tarea de destino e insertar tareas antes o después de esta tarea de destino. Para especificar la tarea de destino, puede modificar vss-extension.json archivo de manifiesto como en el ejemplo siguiente.

vss-extension.json

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id"
            }
        }
    ],
    ...
}

Al configurar la propiedad "targettask", puede especificar el identificador de una tarea de destino. Las tareas se insertarán antes o después de todas las instancias de la tarea de destino especificada.

Especificación de la inserción de entradas de la tarea de destino

Puede especificar una lista de entradas de la tarea de destino que desea insertar como entradas en la tarea insertada.

Esta característica está diseñada para trabajar con tareas de canalización personalizadas. No está pensado para proporcionar acceso a las entradas de la tarea de canalización de destino a través de variables de canalización.

Para obtener acceso a las entradas de la tarea de canalización de destino (entradas con el target_ prefijo), la tarea de canalización insertada debe usar métodos de azure-pipelines-tasks-task-lib y no de las variables de canalización, por ejemplo const inputString = tl.getInput('target_targetInput')).

Para ello, puede crear su propia tarea de canalización personalizada y usar las entradas de destino allí. Si necesita la funcionalidad de una de las tareas integradas, como CmdLine@2, puede crear una copia de la tarea CmdLine@2 y publicarla con la extensión de decorador.

Para especificar esta lista de entradas, puede modificar vss-extension.json archivo de manifiesto como en el ejemplo siguiente.

vss-extension.json (versión de entradas de tareas insertadas)

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id",
                "targettaskinputs": ["target-task-input", "target-task-second-input"]
            }
        }
    ],
    ...
}

Al configurar la propiedad "targettaskinputs", puede especificar la lista de entradas que se espera que se inserten. Estas entradas se insertarán en la tarea con el prefijo "target_" y estarán disponibles en la tarea insertada como target_target-task-input.

Depurar

Es posible que tenga que depurar al crear el decorador. También es posible que desee ver qué datos tiene disponibles en el contexto.

Puede establecer la system.debugContext variable en true al poner en cola una canalización. A continuación, examine la página de resumen de la canalización.

Verá algo similar a la imagen siguiente.

Seleccione la tarea para ver los registros, que muestran los valores en tiempo de ejecución y que el contexto está disponible.

Artículos relacionados

• Acerca de la sintaxis de expresiones YAML
• Contexto de expresión del decorador de canalización
• Desarrollo de una extensión web
• Guía de autenticación