Especifique empregos no seu oleoduto

Azure DevOps Services | Azure DevOps Server | 2020 Azure DevOps Server | 2019 TFS 2018

Nota

No Microsoft Team Foundation Server (TFS) 2018 e nas versões anteriores, os oleodutos de construção e libertação são chamados definições, as corridas são chamadas de construções, as ligações de serviço são chamadas pontos finais de serviço, as fases são chamadas de ambientes, e os empregos são chamados de fases.

Podes organizar o teu oleoduto em empregos. Cada oleoduto tem pelo menos um trabalho. Um trabalho é uma série de passos que correm sequencialmente como uma unidade. Por outras palavras, um trabalho é a unidade de trabalho mais pequena que pode ser programada para executar.

Pode organizar o seu oleoduto de construção ou libertação em empregos. Cada oleoduto tem pelo menos um trabalho. Um trabalho é uma série de passos que correm sequencialmente como uma unidade. Por outras palavras, um trabalho é a unidade de trabalho mais pequena que pode ser programada para executar.

Nota

Deve instalar o TFS 2018.2 para utilizar postos de trabalho em processos de construção. Na TFS 2018 RTM pode utilizar empregos em processos de implementação de lançamento.

Definir um único trabalho

No caso mais simples, um oleoduto tem um único trabalho. Nesse caso, não tem de utilizar explicitamente a job palavra-chave a não ser que esteja a utilizar um modelo. Pode especificar diretamente os passos no seu ficheiro YAML.

Este ficheiro YAML tem um trabalho que funciona com um agente e saídas hospedadosHello worldpela Microsoft.

pool:
  vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"

Pode querer especificar propriedades adicionais nesse trabalho. Nesse caso, pode usar a job palavra-chave.

jobs:
- job: myJob
  timeoutInMinutes: 10
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello world"

O seu oleoduto pode ter vários empregos. Nesse caso, use a jobs palavra-chave.

jobs:
- job: A
  steps:
  - bash: echo "A"

- job: B
  steps:
  - bash: echo "B"

O seu oleoduto pode ter várias fases, cada uma com vários trabalhos. Nesse caso, use a stages palavra-chave.

stages:
- stage: A
  jobs:
  - job: A1
  - job: A2

- stage: B
  jobs:
  - job: B1
  - job: B2

A sintaxe completa para especificar um trabalho é:

- 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

A sintaxe completa para especificar um trabalho é:

- 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

Se a principal intenção do seu trabalho é implementar a sua app (em vez de construir ou testar a sua aplicação), então pode usar um tipo especial de trabalho chamado trabalho de implantação.

A sintaxe para um trabalho de implantação é:

- deployment: string        # instead of job keyword, use deployment keyword
  pool:
    name: string
    demands: string | [ string ]
  environment: string
  strategy:
    runOnce:
      deploy:
        steps:
        - script: echo Hi!

Embora possa adicionar passos para tarefas de implantação num job, recomendamos que utilize um trabalho de implantação. Um trabalho de destacamento tem alguns benefícios. Por exemplo, pode implementar para um ambiente, que inclui benefícios como ser capaz de ver a história do que implementou.

A YAML não é suportada na TFS.

Tipos de empregos

Os empregos podem ser de diferentes tipos, dependendo de onde correm.

  • Os trabalhos de piscina do agente funcionam com um agente numa piscina de agentes.
  • Os trabalhos de servidores funcionam no Azure DevOps Server.
  • Os trabalhos de contentores funcionam num contentor num agente numa piscina de agentes. Para obter mais informações sobre a escolha de contentores, consulte Definir trabalhos de contentores.
  • Os trabalhos de piscina do agente funcionam com um agente numa piscina de agentes.
  • Os trabalhos de servidores funcionam no Azure DevOps Server.
  • Os trabalhos de piscina do agente funcionam com um agente na piscina dos agentes. Estes postos de trabalho estão disponíveis em oleodutos de construção e libertação.
  • Os trabalhos de servidor funcionam na TFS. Estes postos de trabalho estão disponíveis em oleodutos de construção e libertação.
  • Os postos de trabalho do grupo de implantação funcionam em máquinas num grupo de implantação. Estes postos de trabalho só estão disponíveis em gasodutos de libertação.

Trabalhos de piscina de agente

Estes são os trabalhos mais comuns e funcionam com um agente numa piscina de agentes.

  • Quando se utilizam agentes hospedados pela Microsoft, cada trabalho num oleoduto recebe um agente novo.
  • Use exigências com agentes auto-hospedados para especificar que capacidades um agente deve ter para executar o seu trabalho. Pode obter o mesmo agente para trabalhos consecutivos, dependendo se há mais de um agente na sua piscina de agentes que corresponda às exigências do seu oleoduto. Se houver apenas um agente na sua piscina que corresponda às exigências do oleoduto, o oleoduto aguardará até que este agente esteja disponível.

Nota

As exigências e capacidades são concebidas para serem utilizadas com agentes auto-hospedados para que os postos de trabalho possam ser acompanhados por um agente que satisfaça os requisitos do trabalho. Ao utilizar agentes hospedados pela Microsoft, seleciona uma imagem para o agente que corresponde aos requisitos do trabalho, por isso, embora seja possível adicionar capacidades a um agente hospedado pela Microsoft, não precisa de utilizar capacidades com agentes hospedados pela Microsoft.

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

Ou múltiplas exigências:

pool:
  name: myPrivateAgents
  demands:
  - agent.os -equals Darwin
  - anotherCapability -equals somethingElse
steps:
- script: echo hello world

A YAML não é suportada na TFS.

Saiba mais sobre as capacidades dos agentes.

Trabalhos de servidor

As tarefas numa função de servidor são orquestradas e executadas no servidor (Azure Pipelines ou TFS). Um trabalho de servidor não requer um agente ou nenhum computador alvo. Apenas algumas tarefas são suportadas num trabalho de servidor no momento.

Empregos sem agentes apoiados tarefas

Atualmente, apenas as seguintes tarefas são suportadas fora da caixa para trabalhos sem agentes:

Como as tarefas são extensíveis, pode adicionar tarefas mais sem agente utilizando extensões. O tempo limite para trabalhos sem agente é de 60 minutos.

A sintaxe completa para especificar um trabalho de servidor é:

jobs:
- job: string
  timeoutInMinutes: number
  cancelTimeoutInMinutes: number
  strategy:
    maxParallel: number
    matrix: { string: { string: string } }

  pool: server

Também pode utilizar a sintaxe simplificada:

jobs:
- job: string
  pool: server

A YAML não é suportada na TFS.

Dependências

Quando defines vários trabalhos numa única fase, podes especificar dependências entre eles. Os gasodutos devem conter pelo menos um trabalho sem dependências.

Nota

Cada agente só pode gerir um trabalho de cada vez. Para executar vários trabalhos em paralelo, tem de configurar vários agentes. Também precisa de empregos paralelos suficientes.

A sintaxe para definir múltiplos empregos e suas dependências é:

jobs:
- job: string
  dependsOn: string
  condition: string

Exemplo de trabalhos que constroem sequencialmente:

jobs:
- job: Debug
  steps:
  - script: echo hello from the Debug build
- job: Release
  dependsOn: Debug
  steps:
  - script: echo hello from the Release build

Exemplo de trabalhos que se constroem em paralelo (sem dependências):

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

Exemplo de fan-out:

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

Exemplo de fan-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

A YAML não é suportada na TFS.

Condições

Pode especificar as condições em que cada trabalho funciona. Por defeito, um trabalho funciona se não depender de qualquer outro trabalho, ou se todos os empregos de que depende tiverem concluído e sucedido. Você pode personalizar este comportamento forçando um trabalho a executar mesmo que um trabalho anterior falhe ou especificando uma condição personalizada.

Exemplo para gerir um trabalho baseado no estatuto de gerir um trabalho anterior:

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

Exemplo de utilização de uma condição personalizada:

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

Pode especificar que um trabalho é executado com base no valor de uma variável de saída definida num trabalho anterior. Neste caso, só pode utilizar variáveis definidas em empregos diretamente dependentes:

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

A YAML não é suportada na TFS.

Tempos limite

Para evitar a tomada de recursos quando o seu trabalho não responde ou espera demasiado tempo, é uma boa ideia estabelecer um limite para o tempo que o seu trabalho pode executar. Utilize a definição de tempo de trabalho para especificar o limite em minutos para executar o trabalho. Definir o valor para zero significa que o trabalho pode correr:

  • Para sempre em agentes auto-hospedados
  • Durante 360 minutos (6 horas) em agentes hospedados pela Microsoft com um projeto público e repositório público
  • Durante 60 minutos em agentes hospedados pela Microsoft com um projeto privado ou repositório privado (a menos que a capacidade adicional seja paga)

O período de tempo começa quando o trabalho começa a funcionar. Não inclui o tempo em que o trabalho está na fila ou está à espera de um agente.

O timeoutInMinutes permite que seja fixado um limite para o tempo de execução do trabalho. Quando não especificado, o padrão é de 60 minutos. Quando 0 especificado, é utilizado o limite máximo (descrito acima).

O cancelTimeoutInMinutes limite permite que seja definido um limite para o tempo de cancelamento de trabalho quando a tarefa de implantação está definida para continuar a funcionar se uma tarefa anterior falhar. Quando não especificado, o padrão é de 5 minutos. O valor deve variar entre 1 e 35790 minutos.

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

A YAML não é suportada na TFS.

Os empregos direcionados para os agentes hospedados pela Microsoft têm restrições adicionais sobre quanto tempo podem ser executados.

Também pode definir o tempo limite para cada tarefa individualmente - consulte opções de controlo de tarefas.

Configuração multi-trabalho

A partir de um único trabalho que autor, pode executar vários trabalhos em vários agentes em paralelo. Alguns exemplos incluem:

  • Construções multi-configurações: Pode construir várias configurações em paralelo. Por exemplo, pode construir uma aplicação Visual C++ para configurações tanto debugrelease em ambas as x86 plataformas.x64 Para saber mais, consulte Visual Studio Build - múltiplas configurações para várias plataformas.

  • Implementações multi-configurações: Pode executar múltiplas implementações paralelas, por exemplo, para diferentes regiões geográficas.

  • Testes de várias configurações: Pode executar várias configurações em paralelo.

  • A multi-configuração gerará sempre pelo menos um trabalho, mesmo que uma variável multi-configuração esteja vazia.

A matrix estratégia permite que um trabalho seja despachado várias vezes, com diferentes conjuntos variáveis. A maxParallel etiqueta restringe a quantidade de paralelismo. O seguinte trabalho será despachado três vezes com os valores de Localização e Browser definidos conforme especificado. No entanto, apenas dois postos de trabalho serão executados ao mesmo tempo.

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

Nota

Os nomes de configuração da matriz (como US_IE acima) devem conter apenas letras básicas do alfabeto latino (A-Z, a-z), números e sublinhados (_). Devem começar com uma carta. Além disso, devem ter 100 caracteres ou menos.

Também é possível usar variáveis de saída para gerar uma matriz. Isto pode ser útil se precisar gerar a matriz usando um script.

matrix aceitará uma expressão de tempo de execução contendo um objeto JSON cordificado. O objeto JSON, quando expandido, deve coincidir com a sintaxe de matriz. No exemplo abaixo, codificamos a cadeia JSON, mas pode ser gerada por uma linguagem de script ou programa de linha de comando.

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

A YAML não é suportada na TFS.

Corte

Um trabalho de agente pode ser usado para executar um conjunto de testes em paralelo. Por exemplo, você pode executar uma grande suíte de 1000 testes em um único agente. Ou pode usar dois agentes e fazer 500 testes em cada um em paralelo.

Para aproveitar o corte, as tarefas no trabalho devem ser inteligentes o suficiente para entender a fatia a que pertencem.

A tarefa de teste de Visual Studio é uma tarefa que suporta o corte de teste. Se tiver instalado vários agentes, pode especificar como a tarefa de teste de Visual Studio será executada paralelamente a estes agentes.

A parallel estratégia permite que um trabalho seja duplicado muitas vezes. Variáveis System.JobPositionInPhase e System.TotalJobsInPhase são adicionadas a cada trabalho. As variáveis podem então ser usadas dentro dos seus scripts para dividir o trabalho entre os trabalhos. Consulte a execução paralela e múltipla utilizando trabalhos de agente.

O seguinte trabalho será expedido cinco vezes com os valores e System.JobPositionInPhaseSystem.TotalJobsInPhase definidos adequadamente.

jobs:
- job: Test
  strategy:
    parallel: 5

A YAML não é suportada na TFS.

Variáveis de trabalho

Se estiver a utilizar YAML, podem ser especificadas variáveis no trabalho. As variáveis podem ser passadas para entradas de tarefa usando a sintaxe macro $(nome variável), ou acedidas dentro de um script usando a variável de estágio.

Aqui está um exemplo de definir variáveis em um trabalho e usá-las dentro de tarefas.

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"

A YAML não é suportada na TFS.

Para obter informações sobre a utilização de uma condição, consulte as condições de especificação.

Área de trabalho

Quando se gere um trabalho de piscina de agentes, cria-se um espaço de trabalho no agente. O espaço de trabalho é um diretório no qual descarrega a fonte, executa passos e produz saídas. O diretório do espaço de trabalho pode ser referenciado no seu trabalho usando Pipeline.Workspace variável. Neste âmbito, são criadas várias subdiretivas:

Quando se gere um trabalho de piscina de agentes, cria-se um espaço de trabalho no agente. O espaço de trabalho é um diretório no qual descarrega a fonte, executa passos e produz saídas. O diretório do espaço de trabalho pode ser referenciado no seu trabalho usando Agent.BuildDirectory variável. Neste âmbito, são criadas várias subdiretivas:

  • Build.SourcesDirectory é onde as tarefas descarregam o código fonte da aplicação.
  • Build.ArtifactStagingDirectory é onde as tarefas descarregam artefactos necessários para o oleoduto ou carregam artefactos antes de serem publicados.
  • Build.BinariesDirectory é onde as tarefas escrevem as suas saídas.
  • Common.TestResultsDirectory é onde as tarefas fazem o upload dos resultados dos seus testes.

O $(Build.ArtifactStagingDirectory) e $(Common.TestResultsDirectory) são sempre apagados e recriados antes de cada construção.

Quando se executa um oleoduto sobre um agente auto-hospedado, por defeito, nenhuma das subdireições além de $(Build.ArtifactStagingDirectory) e $(Common.TestResultsDirectory) são limpas entre duas corridas consecutivas. Como resultado, pode fazer construções e implementações incrementais, desde que sejam implementadas tarefas para fazer uso disso. Pode anular este comportamento usando a workspace definição do trabalho.

Importante

As opções de limpeza do espaço de trabalho são aplicáveis apenas para agentes auto-hospedados. Quando se utilizam agentes hospedados pela Microsoft, o trabalho é sempre executado num novo agente.

- job: myJob
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

Quando especifica uma das clean opções, são interpretadas da seguinte forma:

  • outputs: Excluir Build.BinariesDirectory antes de executar um novo emprego.
  • resources: Excluir Build.SourcesDirectory antes de executar um novo emprego.
  • all: Eliminar todo Pipeline.Workspace o diretório antes de executar um novo emprego.
  jobs:
  - deployment: MyDeploy
    pool:
      vmImage: 'ubuntu-latest'
    workspace:
      clean: all
    environment: staging

Nota

Dependendo das capacidades do seu agente e das exigências do pipeline, cada trabalho pode ser encaminhado para um agente diferente na sua piscina auto-hospedada. Como resultado, você pode obter um novo agente para posteriores corridas de gasodutos (ou estágios ou empregos no mesmo oleoduto), por isso não a limpeza não é uma garantia de que as execuções subsequentes, empregos ou estágios serão capazes de aceder a saídas de execuções, empregos ou estágios anteriores. Pode configurar as capacidades dos agentes e as exigências do gasoduto para especificar quais os agentes utilizados para executar um trabalho de oleoduto, mas a menos que haja apenas um único agente na piscina que satisfaça as exigências, não há garantias de que os empregos subsequentes utilizem o mesmo agente que os trabalhos anteriores. Para obter mais informações, consulte Especificar as exigências.

Além de limpar o espaço de trabalho, também pode configurar a limpeza configurando a definição Clean nas definições de tubagem UI. Quando a definição Clean é verdadeira , é equivalente a especificar clean: true cada passo de saída no seu pipeline. Para configurar a definição Clean :

  1. Edite o seu pipeline, escolha ...e selecione Triggers.

    Edit triggers.

  2. Selecione YAML, Obtenha fontes e configufique a definição de Limpeza desejada. O padrão é falso.

    Clean setting.

A YAML não é suportada na TFS.

Download de artefactos

Este ficheiro exemplo YAML publica o artefacto WebSite e, em seguida, descarrega o artefacto para $(Pipeline.Workspace). O trabalho de implantação só funciona se o trabalho de Construção for bem sucedido.

# 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()

A YAML não é suportada na TFS.

Para obter informações sobre a utilização de dependOn e condição, consulte Condições de Especificação.

Acesso ao token OAuth

Pode permitir que scripts em execução em um trabalho acedam aos atuais Pipelines Azure ou token de segurança TFS OAuth. O token pode ser usado para autenticar na API dos Gasodutos Azure.

O símbolo OAuth está sempre disponível para os oleodutos YAML. Deve ser explicitamente mapeado para a tarefa ou passo de utilização env. Eis um exemplo:

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)

A YAML não é suportada na TFS.

Passos seguintes