Указание заданий в конвейере
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018
Примечание
В Microsoft Team Foundation Server (TFS) 2018 и предыдущих версий конвейеры сборки и выпуска называются определениями, выполнения называются сборками, подключения к службам называются конечными точками служб, этапы называются средами, а задания называются этапами.
Конвейер можно упорядочить в задания. Каждый конвейер имеет по крайней мере одно задание. Задание — это ряд шагов, которые выполняются последовательно как единое целое. Иными словами, задание — это наименьшая единица работы, которую можно запланировать для выполнения.
Конвейер сборки или выпуска можно организовать в задания. Каждый конвейер имеет по крайней мере одно задание. Задание — это ряд шагов, которые выполняются последовательно как единое целое. Иными словами, задание — это наименьшая единица работы, которую можно запланировать для выполнения.
Примечание
Чтобы использовать задания в процессах сборки, необходимо установить TFS 2018.2. В TFS 2018 RTM можно использовать задания в процессах развертывания выпусков.
Определение одного задания
В простейшем случае конвейер имеет одно задание. В этом случае не нужно явно использовать ключевое слово , job
если вы не используете шаблон. Вы можете напрямую указать шаги в файле YAML.
Этот ФАЙЛ YAML содержит задание, которое выполняется в агенте, размещенном в Майкрософт, и выводит выходные Hello world
данные .
pool:
vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"
Может потребоваться указать дополнительные свойства для этого задания. В этом случае можно использовать ключевое job
слово .
jobs:
- job: myJob
timeoutInMinutes: 10
pool:
vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"
В конвейере может быть несколько заданий. В этом случае используйте ключевое jobs
слово .
jobs:
- job: A
steps:
- bash: echo "A"
- job: B
steps:
- bash: echo "B"
Конвейер может иметь несколько этапов, каждый из которых имеет несколько заданий. В этом случае используйте ключевое stages
слово .
stages:
- stage: A
jobs:
- job: A1
- job: A2
- stage: B
jobs:
- job: B1
- job: B2
Полный синтаксис задания:
- job: string # name of the job, A-Z, a-z, 0-9, and underscore
displayName: string # friendly name to display in the UI
dependsOn: string | [ string ]
condition: string
strategy:
parallel: # parallel strategy
matrix: # matrix strategy
maxParallel: number # maximum number simultaneous matrix legs to run
# note: `parallel` and `matrix` are mutually exclusive
# you may specify one or the other; including both is an error
# `maxParallel` is only valid with `matrix`
continueOnError: boolean # 'true' if future jobs should run even if this job fails; defaults to 'false'
pool: pool # agent pool
workspace:
clean: outputs | resources | all # what to clean up before the job runs
container: containerReference # container to run this job inside
timeoutInMinutes: number # how long to run the job before automatically cancelling
cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
variables: { string: string } | [ variable | variableReference ]
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
services: { string: string | container } # container resources to run as a service container
Полный синтаксис задания:
- job: string # name of the job, A-Z, a-z, 0-9, and underscore
displayName: string # friendly name to display in the UI
dependsOn: string | [ string ]
condition: string
strategy:
parallel: # parallel strategy
matrix: # matrix strategy
maxParallel: number # maximum number simultaneous matrix legs to run
# note: `parallel` and `matrix` are mutually exclusive
# you may specify one or the other; including both is an error
# `maxParallel` is only valid with `matrix`
continueOnError: boolean # 'true' if future jobs should run even if this job fails; defaults to 'false'
pool: pool # agent pool
workspace:
clean: outputs | resources | all # what to clean up before the job runs
container: containerReference # container to run this job inside
timeoutInMinutes: number # how long to run the job before automatically cancelling
cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
variables: { string: string } | [ variable | variableReference ]
steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
services: { string: string | container } # container resources to run as a service container
uses: # Any resources (repos or pools) required by this job that are not already referenced
repositories: [ string ] # Repository references to Azure Git repositories
pools: [ string ] # Pool names, typically when using a matrix strategy for the job
Если основной целью задания является развертывание приложения (в отличие от сборки или тестирования приложения), можно использовать особый тип задания, который называется заданием развертывания.
Для задания развертывания используется следующий синтаксис:
- deployment: string # instead of job keyword, use deployment keyword
pool:
name: string
demands: string | [ string ]
environment: string
strategy:
runOnce:
deploy:
steps:
- script: echo Hi!
Хотя шаги для задач развертывания можно добавить в job
, рекомендуется использовать задание развертывания. Задание развертывания имеет несколько преимуществ. Например, вы можете выполнить развертывание в среде, которая включает в себя такие преимущества, как возможность просматривать журнал развернутых объектов.
YAML не поддерживается в TFS.
Типы заданий
Задания могут быть разных типов в зависимости от того, где они выполняются.
- Задания пула агентов выполняются агентом в пуле агентов.
- Задания сервера выполняются на сервере Azure DevOps Server.
- Задания контейнеров выполняются в контейнере на агенте в пуле агентов. Дополнительные сведения о выборе контейнеров см. в разделе Определение заданий контейнеров.
- Задания пула агентов выполняются агентом в пуле агентов.
- Задания сервера выполняются на сервере Azure DevOps Server.
- Задания пула агентов выполняются на агенте в пуле агентов. Эти задания доступны в конвейерах сборки и выпуска.
- Задания сервера выполняются в TFS. Эти задания доступны в конвейерах сборки и выпуска.
- Задания группы развертывания выполняются на компьютерах в группе развертывания. Эти задания доступны только в конвейерах выпуска.
Задания пула агентов
Это наиболее распространенный тип заданий, которые выполняются на агенте в пуле агентов.
- При использовании Майкрософт размещенных агентов каждое задание в конвейере получает новый агент.
- Используйте требования с локальными агентами, чтобы указать, какие возможности должны быть у агента для выполнения задания. Вы можете получить один и тот же агент для последовательных заданий в зависимости от того, есть ли в пуле агентов несколько агентов, соответствующих требованиям конвейера. Если в пуле есть только один агент, соответствующий требованиям конвейера, конвейер будет ожидать, пока этот агент не станет доступен.
Примечание
Требования и возможности предназначены для использования с локальными агентами, чтобы задания можно было сопоставить с агентом, отвечающим требованиям задания. При использовании агентов, размещенных в Майкрософт, для агента выбирается образ, соответствующий требованиям задания, поэтому, хотя можно добавить возможности в агент, размещенный в Майкрософт, использовать возможности с агентами, размещенными в Майкрософт, не нужно.
pool:
name: myPrivateAgents # your job runs on an agent in this pool
demands: agent.os -equals Windows_NT # the agent must have this capability to run the job
steps:
- script: echo hello world
Или несколько требований:
pool:
name: myPrivateAgents
demands:
- agent.os -equals Darwin
- anotherCapability -equals somethingElse
steps:
- script: echo hello world
YAML не поддерживается в TFS.
Узнайте больше о возможностях агента.
Задания сервера
Задачи в задании сервера оркестрируются и выполняются на сервере (Azure Pipelines или TFS). Для задания сервера не требуется агент или какие-либо целевые компьютеры. В настоящее время в задании сервера поддерживается только несколько задач.
Задачи, поддерживаемые задания без агента
В настоящее время для заданий без агента поддерживаются только следующие задачи:
- Задача "Задержка"
- Задача "Вызов функции Azure"
- Вызов задачи REST API
- Задача проверки вручную
- Задача "Публикация в Служебная шина Azure"
- Задача "Запрос оповещений Azure Monitor"
- Задача "Запрос рабочих элементов"
Так как задачи являются расширяемыми, можно добавить дополнительные задачи без агента с помощью расширений. Время ожидания по умолчанию для заданий без агента составляет 60 минут.
Полный синтаксис для указания задания сервера:
jobs:
- job: string
timeoutInMinutes: number
cancelTimeoutInMinutes: number
strategy:
maxParallel: number
matrix: { string: { string: string } }
pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job
Можно также использовать упрощенный синтаксис:
jobs:
- job: string
pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job
YAML не поддерживается в TFS.
Зависимости
При определении нескольких заданий на одном этапе можно указать зависимости между ними. Конвейеры должны содержать по крайней мере одно задание без зависимостей.
Примечание
Каждый агент может одновременно выполнять только одно задание. Для параллельного выполнения нескольких заданий необходимо настроить несколько агентов. Кроме того, требуется достаточное количество параллельных заданий.
Синтаксис для определения нескольких заданий и их зависимостей:
jobs:
- job: string
dependsOn: string
condition: string
Примеры заданий, которые создаются последовательно:
jobs:
- job: Debug
steps:
- script: echo hello from the Debug build
- job: Release
dependsOn: Debug
steps:
- script: echo hello from the Release build
Примеры заданий, которые выполняются параллельно (без зависимостей):
jobs:
- job: Windows
pool:
vmImage: 'windows-latest'
steps:
- script: echo hello from Windows
- job: macOS
pool:
vmImage: 'macOS-latest'
steps:
- script: echo hello from macOS
- job: Linux
pool:
vmImage: 'ubuntu-latest'
steps:
- script: echo hello from Linux
Пример развертывания:
jobs:
- job: InitialJob
steps:
- script: echo hello from initial job
- job: SubsequentA
dependsOn: InitialJob
steps:
- script: echo hello from subsequent A
- job: SubsequentB
dependsOn: InitialJob
steps:
- script: echo hello from subsequent B
Пример фан-in:
jobs:
- job: InitialA
steps:
- script: echo hello from initial A
- job: InitialB
steps:
- script: echo hello from initial B
- job: Subsequent
dependsOn:
- InitialA
- InitialB
steps:
- script: echo hello from subsequent
YAML не поддерживается в TFS.
Условия
Вы можете указать условия для выполнения каждого задания. По умолчанию задание выполняется, если оно не зависит от других заданий или если все задания, от которых оно зависит, завершены и успешно завершены. Это поведение можно настроить путем принудительного выполнения задания, даже если предыдущее задание завершается сбоем, или путем указания настраиваемого условия.
Пример запуска задания на основе состояния выполнения предыдущего задания:
jobs:
- job: A
steps:
- script: exit 1
- job: B
dependsOn: A
condition: failed()
steps:
- script: echo this will run when A fails
- job: C
dependsOn:
- A
- B
condition: succeeded('B')
steps:
- script: echo this will run when B runs and succeeds
Пример использования настраиваемого условия:
jobs:
- job: A
steps:
- script: echo hello
- job: B
dependsOn: A
condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/master'))
steps:
- script: echo this only runs for master
Можно указать, что задание выполняется на основе значения выходной переменной, заданной в предыдущем задании. В этом случае можно использовать только переменные, заданные в непосредственно зависимых заданиях:
jobs:
- job: A
steps:
- script: "echo '##vso[task.setvariable variable=skipsubsequent;isOutput=true]false'"
name: printvar
- job: B
condition: and(succeeded(), ne(dependencies.A.outputs['printvar.skipsubsequent'], 'true'))
dependsOn: A
steps:
- script: echo hello from B
YAML не поддерживается в TFS.
Истекшее время ожидания
Чтобы избежать использования ресурсов, когда задание не отвечает или ожидает слишком долго, рекомендуется установить ограничение на продолжительность выполнения задания. Используйте параметр времени ожидания задания, чтобы указать ограничение в минутах для выполнения задания. Установка нулевого значения означает, что задание может выполняться:
- Навсегда на локальных агентах
- В течение 360 минут (6 часов) на Майкрософт размещенных агентах с общедоступным проектом и общедоступным репозиторием
- В течение 60 минут на Майкрософт размещенных агентов с частным проектом или частным репозиторием (если не оплачивается дополнительная емкость).
Период ожидания начинается с начала выполнения задания. Он не включает время постановки задания в очередь или ожидания агента.
позволяет timeoutInMinutes
задать ограничение на время выполнения задания. Если значение не указано, значение по умолчанию — 60 минут. Если 0
задано значение , используется максимальное ограничение (описано выше).
Позволяет cancelTimeoutInMinutes
установить ограничение на время отмены задания, если задача развертывания будет продолжать выполняться в случае сбоя предыдущей задачи. Если значение не указано, значение по умолчанию — 5 минут. Значение должно находиться в диапазоне от 1 до 35790 минут.
jobs:
- job: Test
timeoutInMinutes: 10 # how long to run the job before automatically cancelling
cancelTimeoutInMinutes: 2 # how much time to give 'run always even if cancelled tasks' before stopping them
YAML не поддерживается в TFS.
Задания, предназначенные для Майкрософт размещенных агентов, имеют дополнительные ограничения на продолжительность их выполнения.
Вы также можете задать время ожидания для каждой задачи по отдельности. См. раздел Параметры управления задачами.
Настройка нескольких заданий
Из одного задания, который вы создаете, можно параллельно выполнять несколько заданий на нескольких агентах. Некоторые примеры:
Сборки с несколькими конфигурациями: Вы можете создавать несколько конфигураций параллельно. Например, можно создать приложение Visual C++ для конфигураций
debug
иrelease
наx86
платформах иx64
. Дополнительные сведения см. в статье Сборка Visual Studio — несколько конфигураций для нескольких платформ.Развертывания с несколькими конфигурациями: Вы можете выполнять несколько развертываний в параллельном режиме, например в разных географических регионах.
Тестирование с несколькими конфигурациями. Вы можете параллельно тестировать несколько конфигураций.
При использовании нескольких конфигураций всегда создается по крайней мере одно задание, даже если переменная с несколькими конфигурациями пуста.
Стратегия matrix
позволяет многократно отправлять задание с разными наборами переменных. Тег maxParallel
ограничивает количество параллелизма. Следующее задание будет отправлено три раза с заданными значениями Location и Browser. Однако одновременно будут выполняться только два задания.
jobs:
- job: Test
strategy:
maxParallel: 2
matrix:
US_IE:
Location: US
Browser: IE
US_Chrome:
Location: US
Browser: Chrome
Europe_Chrome:
Location: Europe
Browser: Chrome
Примечание
Имена конфигурации матрицы (как описано US_IE
выше) должны содержать только базовые латинские буквы (A–Z, a–z), цифры и символы подчеркивания (_
).
Имя должно начинаться с буквы.
Кроме того, они должны содержать не более 100 символов.
Для создания матрицы также можно использовать выходные переменные . Это может быть удобно, если необходимо создать матрицу с помощью скрипта.
matrix
принимает выражение среды выполнения, содержащее строковый объект JSON.
Этот объект JSON при развертывании должен соответствовать синтаксису матрицы.
В приведенном ниже примере мы жестко закодировали строку JSON, но ее можно создать с помощью языка сценариев или программы командной строки.
jobs:
- job: generator
steps:
- bash: echo "##vso[task.setVariable variable=legs;isOutput=true]{'a':{'myvar':'A'}, 'b':{'myvar':'B'}}"
name: mtrx
# This expands to the matrix
# a:
# myvar: A
# b:
# myvar: B
- job: runner
dependsOn: generator
strategy:
matrix: $[ dependencies.generator.outputs['mtrx.legs'] ]
steps:
- script: echo $(myvar) # echos A or B depending on which leg is running
YAML не поддерживается в TFS.
Фрагментирование
Задание агента можно использовать для параллельного выполнения набора тестов. Например, можно запустить большой набор из 1000 тестов на одном агенте. Кроме того, можно использовать два агента и параллельно выполнять 500 тестов на каждом из них.
Чтобы использовать срезы, задачи в задании должны быть достаточно умными, чтобы понять, к какому срезу они принадлежат.
Тестовая задача Visual Studio — это одна из таких задач, которая поддерживает срезы тестов. Если установлено несколько агентов, можно указать, как задача тестирования Visual Studio будет выполняться параллельно на этих агентах.
Стратегия parallel
позволяет многократно дублировать задание.
Переменные System.JobPositionInPhase
и System.TotalJobsInPhase
добавляются в каждое задание. Затем переменные можно использовать в скриптах для разделения работы между заданиями.
См. статью Параллельное и несколько выполнений с помощью заданий агента.
Следующее задание будет отправлено пять раз со значениями System.JobPositionInPhase
и System.TotalJobsInPhase
соответствующим образом задано.
jobs:
- job: Test
strategy:
parallel: 5
YAML не поддерживается в TFS.
Переменные задания
Если вы используете YAML, в задании можно указать переменные. Переменные можно передать во входные данные задачи с помощью синтаксиса макроса $(variableName) или получить доступ к скрипту с помощью переменной этапа.
Ниже приведен пример определения переменных в задании и их использования в задачах.
variables:
mySimpleVar: simple var value
"my.dotted.var": dotted var value
"my var with spaces": var with spaces value
steps:
- script: echo Input macro = $(mySimpleVar). Env var = %MYSIMPLEVAR%
condition: eq(variables['agent.os'], 'Windows_NT')
- script: echo Input macro = $(mySimpleVar). Env var = $MYSIMPLEVAR
condition: in(variables['agent.os'], 'Darwin', 'Linux')
- bash: echo Input macro = $(my.dotted.var). Env var = $MY_DOTTED_VAR
- powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES"
YAML не поддерживается в TFS.
Сведения об использовании условия см. в разделе Указание условий.
Рабочая область
При выполнении задания пула агентов создается рабочая область на агенте. Рабочая область — это каталог, в который она скачивает источник, выполняет шаги и создает выходные данные. На каталог рабочей области можно ссылаться в задании с помощью Pipeline.Workspace
переменной . При этом создаются различные подкаталоги:
При выполнении задания пула агентов создается рабочая область на агенте. Рабочая область — это каталог, в который она скачивает источник, выполняет шаги и создает выходные данные. На каталог рабочей области можно ссылаться в задании с помощью Agent.BuildDirectory
переменной . При этом создаются различные подкаталоги:
Build.SourcesDirectory
— это место, где задачи загружают исходный код приложения.Build.ArtifactStagingDirectory
— это место, где задачи загружают артефакты, необходимые для конвейера, или передают артефакты перед их публикацией.Build.BinariesDirectory
— это место, где задачи записывают свои выходные данные.Common.TestResultsDirectory
— это место, куда задачи отправляют результаты теста.
И $(Build.ArtifactStagingDirectory)
$(Common.TestResultsDirectory)
всегда удаляются и создаются повторно перед каждой сборкой.
При запуске конвейера в локальном агенте по умолчанию ни один из подкаталогов, кроме $(Build.ArtifactStagingDirectory)
и $(Common.TestResultsDirectory)
, не очищаются между двумя последовательными запусками. В результате можно выполнять добавочные сборки и развертывания при условии, что для их использования реализованы задачи. Это поведение можно переопределить с помощью workspace
параметра задания.
Важно!
Параметры очистки рабочей области применимы только к локальным агентам. При использовании агентов, размещенных Майкрософт, задание всегда выполняется на новом агенте.
- job: myJob
workspace:
clean: outputs | resources | all # what to clean up before the job runs
При указании clean
одного из параметров они интерпретируются следующим образом:
outputs
: удалениеBuild.BinariesDirectory
перед выполнением нового задания.resources
: удалениеBuild.SourcesDirectory
перед выполнением нового задания.all
: перед выполнением нового задания удалите весьPipeline.Workspace
каталог.
jobs:
- deployment: MyDeploy
pool:
vmImage: 'ubuntu-latest'
workspace:
clean: all
environment: staging
Примечание
В зависимости от возможностей агента и требований конвейера каждое задание может быть перенаправлено в другой агент в локальном пуле. В результате вы можете получить новый агент для последующих запусков конвейера (или этапов или заданий в том же конвейере), поэтому отсутствие очистки не гарантирует, что последующие запуски, задания или этапы смогут получить доступ к выходным данным предыдущих запусков, заданий или этапов. Вы можете настроить возможности агента и требования конвейера, чтобы указать, какие агенты используются для выполнения задания конвейера, но если в пуле нет только одного агента, удовлетворяющего требованиям, нет никакой гарантии, что последующие задания будут использовать тот же агент, что и предыдущие задания. Дополнительные сведения см. в разделе Указание требований.
Помимо очистки рабочей области можно также настроить очистку, настроив параметр Очистить в пользовательском интерфейсе параметров конвейера. Если для параметра Clean задано значение true, которое также является значением по умолчанию, это эквивалентно указанию для каждого шага оформленияclean: true
заказа в конвейере. При указании clean: true
перед получением git reset --hard HEAD
git вы выполните команду git clean -ffdx
, а затем выполните команду . Чтобы настроить параметр Очистка , выполните следующие действия.
Измените конвейер, выберите ..., а затем — Триггеры.
Выберите YAML, Получить источники и настройте нужный параметр Очистка . Значение по умолчанию — true.
YAML не поддерживается в TFS.
Скачивание артефакта
В этом примере yaml-файла публикуется артефакт WebSite
, а затем он загружается в $(Pipeline.Workspace)
. Задание Deploy запускается только в том случае, если задание сборки выполнено успешно.
# test and upload my code as an artifact named WebSite
jobs:
- job: Build
pool:
vmImage: 'ubuntu-latest'
steps:
- script: npm test
- task: PublishBuildArtifacts@1
inputs:
pathtoPublish: '$(System.DefaultWorkingDirectory)'
artifactName: WebSite
# download the artifact and deploy it only if the build job succeeded
- job: Deploy
pool:
vmImage: 'ubuntu-latest'
steps:
- checkout: none #skip checking out the default repository resource
- task: DownloadBuildArtifacts@0
displayName: 'Download Build Artifacts'
inputs:
artifactName: WebSite
downloadPath: $(System.DefaultWorkingDirectory)
dependsOn: Build
condition: succeeded()
YAML не поддерживается в TFS.
Сведения об использовании dependsOn и условия см. в разделе Указание условий.
Доступ к токену OAuth
Вы можете разрешить скриптам, выполняемым в задании, доступ к текущему маркеру безопасности Azure Pipelines или TFS OAuth. Маркер можно использовать для проверки подлинности в REST API Azure Pipelines.
Маркер OAuth всегда доступен для конвейеров YAML.
Его необходимо явно сопоставить с задачей или шагом с помощью env
.
Ниже приведен пример:
steps:
- powershell: |
$url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=4.1-preview"
Write-Host "URL: $url"
$pipeline = Invoke-RestMethod -Uri $url -Headers @{
Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
}
Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"
env:
SYSTEM_ACCESSTOKEN: $(system.accesstoken)
YAML не поддерживается в TFS.