Разработка декоратора конвейера

Статья
10/28/2023

Azure DevOps Services | Azure DevOps Server 2022

Декораторы конвейеров позволяют добавлять шаги в начало и конец каждого задания. Процесс разработки декоратора конвейера отличается от добавления шагов в одно определение, так как он применяется ко всем конвейерам в организации.

Предположим, что вашей организации требуется запустить сканер вирусов во всех выходных данных сборки, которые могут быть выпущены. Авторам конвейера не нужно помнить, чтобы добавить этот шаг. Мы создадим декоратор, который автоматически внедряет шаг. Наш декоратор конвейера внедряет пользовательскую задачу, которая выполняет сканирование вирусов в конце каждого задания конвейера.

Совет

Ознакомьтесь с нашей новой документацией по разработке расширений с помощью пакета SDK для расширений Azure DevOps.

1. Добавление вкладов в расширение

В следующем примере предполагается, что вы знакомы с моделями вклада.

Создайте расширение. После создания расширения у вас есть vss-extension.json файл.
Добавьте вклад в vss-extension.json файл для нового декоратора конвейера.

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"
        }
    ]
}

Варианты вклада

Давайте рассмотрим свойства и то, что они используются для:

Свойство	Description
`id`	Идентификатор вклада. Должен быть уникальным среди вкладов в это расширение.
`type`	Указывает, что этот вклад является декоратором конвейера. Должен быть строкой `ms.azure-pipelines.pipeline-decorator`.
`targets`	Декораторы могут выполняться до задания или указанной задачи, после или обоих. Сведения о доступных параметрах см. в следующей таблице.
`properties.template`	(обязательно) Шаблон — это файл YAML, включенный в расширение, который определяет шаги для декоратора конвейера. Это относительный путь из корневой папки расширения.
`properties.targettask`	Идентификатор целевой задачи, используемый для `ms.azure-pipelines-agent-job.pre-task-tasks` или `ms.azure-pipelines-agent-job.post-task-tasks` целевых объектов. Должна быть строка GUID, например `89b8ac58-8cb7-4479-a362-1baaacc6c7ad`

Целевые объекты

Назначение	Description
`ms.azure-pipelines-agent-job.pre-job-tasks`	Выполнение перед другими задачами в классическом конвейере сборки или YAML. Из-за различий в том, как происходит проверка исходного кода, этот целевой объект выполняется после проверка out в конвейере YAML, но до проверка out в классическом конвейере сборки.
`ms.azure-pipelines-agent-job.post-checkout-tasks`	Выполните последнюю `checkout` задачу в классическом конвейере сборки или YAML.
`ms.azure-pipelines-agent-job.post-job-tasks`	Запустите после других задач в классическом конвейере сборки или YAML.
`ms.azure-pipelines-agent-job.pre-task-tasks`	Выполните перед указанной задачей в классическом конвейере сборки или YAML.
`ms.azure-pipelines-agent-job.post-task-tasks`	Запустите после указанной задачи в классическом конвейере сборки или YAML.
`ms.azure-release-pipelines-agent-job.pre-task-tasks`	Выполните перед указанной задачей в классическом конвейере RM.
`ms.azure-release-pipelines-agent-job.post-task-tasks`	Запустите после указанной задачи в классическом конвейере RM.
`ms.azure-release-pipelines-agent-job.pre-job-tasks`	Выполнение перед другими задачами в классическом конвейере RM.
`ms.azure-release-pipelines-agent-job.post-job-tasks`	Запустите после других задач в классическом конвейере RM.

Примечание.

Задания развертывания в конвейере YAML поддерживаются ms.azure-pipelines-agent-job.pre-job-tasks только и ms.azure-pipelines-agent-job.post-job-tasks целевые объекты. Задания поддерживают все целевые объекты конвейера YAML.

В этом примере мы используем ms.azure-pipelines-agent-job.post-job-tasks , так как мы хотим запустить в конце всех заданий сборки.

Это расширение способствует декоратору конвейера. Затем мы создадим файл YAML шаблона, чтобы определить поведение декоратора.

2. Создание файла YAML декоратора

В свойствах расширения мы выбрали имя my-decorator.yml. Создайте этот файл в корне вашего вклада. Он содержит набор шагов, выполняемых после каждого задания. Начнем с базового примера и начнем с полной задачи.

my-декоратор.yml (начальная версия)

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

Примечание.

Задачи декоратора конвейера с использованием подключения к службе не поддерживаются для классических конвейеров выпуска.

3. Установка декоратора

Чтобы добавить декоратор конвейера в организацию, необходимо установить расширение. Только частные расширения могут способствовать декораторам конвейера. Расширение должно быть создано и предоставлено вашей организации, прежде чем его можно будет использовать.

После того как расширение будет предоставлено вашей организации, найдите расширение и установите его.

Сохраните файл, а затем создайте и установите расширение. Создайте и запустите базовый конвейер. Декоратор автоматически внедряет наш dir сценарий в конце каждого задания. Запуск конвейера выглядит примерно так, как показано в следующем примере.

Pipeline decorator running a simple script

Примечание.

Декоратор выполняется на каждом задании в каждом конвейере в организации. В последующих шагах мы добавим логику для управления тем, когда и как выполняется декоратор.

4. Внедрение условий

В нашем примере необходимо запустить сканер вирусов только в том случае, если выходные данные сборки могут быть выпущены для общественности. Предположим, что когда-либо выпускаются только сборки из ветвь по умолчанию (обычноmain). Мы должны ограничить декоратор заданиями, выполняемыми в ветвь по умолчанию.

Обновленный файл выглядит следующим образом:

my-декоратор.yml (обновленная версия)

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

Вы можете начать видеть силу этой точки расширяемости. Используйте контекст текущего задания для условного внедрения шагов во время выполнения. Используйте выражения YAML, чтобы принимать решения о том, какие шаги следует внедрять и когда. Полный список доступных данных см . в контексте выражения декоратора конвейера.

Существует еще одно условие, которое необходимо рассмотреть: что, если пользователь уже включил шаг сканирования вируса? Мы не должны тратить время на его выполнение снова. В этом простом примере мы притворяемся тем, что любая script задача, найденная в задании, выполняет сканер вирусов. (В реальной реализации у вас была бы настраиваемая задача, чтобы проверка для этого.)

Идентификатор d9bafed4-0b18-4f58-968d-86655b4d2ce9задачи скрипта. Если мы видим другую задачу скрипта, мы не должны внедрять наши задачи.

my-декоратор.yml (окончательная версия)

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. Указание целевой задачи

Можно указать идентификатор целевой задачи и внедрить задачи до или после этой целевой задачи. Чтобы указать целевую задачу, можно изменить файл манифеста vss-extension.json, как показано в следующем примере.

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"
            }
        }
    ],
    ...
}

При настройке свойства targettask можно указать идентификатор целевой задачи. Задачи будут внедрены до и после всех экземпляров указанной целевой задачи.

Указание входных данных целевой задачи

Можно указать список входных данных целевой задачи, которые необходимо внедрить в качестве входных данных для внедренной задачи.

Эта функция предназначена для работы с пользовательскими задачами конвейера. Он не предназначен для предоставления доступа к целевым входным данным задачи конвейера через переменные конвейера.

Чтобы получить доступ к входным данным задачи целевого конвейера (входные данные с target_ префиксом), внедренная задача конвейера должна использовать методы из azure-pipelines-tasks-task-lib, а не переменных конвейера, например const inputString = tl.getInput('target_targetInput')).

Для этого можно создать собственную настраиваемую задачу конвейера и использовать в нем целевые входные данные. Если вам нужна функциональность одной из встроенных задач, например CmdLine@2, можно создать копию задачи CmdLine@2 и опубликовать ее с расширением декоратора.

Примечание.

Эта функция доступна только для задач, которые внедряются до или после целевой задачи.

Чтобы указать этот список входных данных, можно изменить файл манифеста vss-extension.json, как показано в следующем примере.

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",
                "targettaskinputs": ["target-task-input", "target-task-second-input"]
            }
        }
    ],
    ...
}

Настроив свойство targettaskinputs, можно указать список входных данных, которые должны быть внедрены. Эти входные данные будут внедрены в задачу с префиксом "target_" и будут доступны в внедренной задаче, например target_target-task-input.

Примечание.

Целевые входные данные задач, которые получают секретные значения с переменными или получают их из других задач, не будут внедряться.

Отладка

При создании декоратора может потребоваться выполнить отладку. Кроме того, может потребоваться узнать, какие данные доступны в контексте.

Переменная true может быть задана при system.debugContext очереди конвейера. Затем просмотрите страницу сводки конвейера.

Вы увидите что-то подобное следующему изображению.

View pipeline decorator context

Выберите задачу, чтобы просмотреть журналы, отображающие значения среды выполнения и доступные контексты.

Разработка декоратора конвейера

1. Добавление вкладов в расширение

vss-extension.json

Варианты вклада

Целевые объекты

2. Создание файла YAML декоратора

my-декоратор.yml (начальная версия)

3. Установка декоратора

4. Внедрение условий

my-декоратор.yml (обновленная версия)

my-декоратор.yml (окончательная версия)

5. Указание целевой задачи

vss-extension.json

Указание входных данных целевой задачи

vss-extension.json (внедренная версия входных данных задачи)

Отладка

Обратная связь

Обратная связь

Дополнительные ресурсы

Разработка декоратора конвейера

1. Добавление вкладов в расширение

vss-extension.json

Варианты вклада

Целевые объекты

2. Создание файла YAML декоратора

my-декоратор.yml (начальная версия)

3. Установка декоратора

4. Внедрение условий

my-декоратор.yml (обновленная версия)

my-декоратор.yml (окончательная версия)

5. Указание целевой задачи

vss-extension.json

Указание входных данных целевой задачи

vss-extension.json (внедренная версия входных данных задачи)

Отладка

Связанные статьи

Обратная связь

Обратная связь

Дополнительные ресурсы