Receita de CI/CD: pipelines do Azure

Esta página fornece um azure-pipelines.yml completo que instala a CLI, autentica com um Aplicativo Externo, empacota e publica uma Solução da UiPath, a implanta no Orchestrator e executa um pacote do Test Manager na implantação. O pipeline é independente: copie-o para a raiz do seu repositório, conecte dois segredos e ele será executado.

Para os princípios subjacentes — autenticação, cache, pré-instalação de ferramentas, aplicação de versão — consulte Como fazer: implantar no Orchestrator a partir de CI. Esta página se concentra na sintaxe do Azure Pipelines.

Pré-requisitos

Antes de copiar o YAML abaixo:

1. Crie um aplicativo externo na UiPath com os escopos OR.* de que seu pipeline precisa. Consulte Autenticação — Fluxo 2.
2. Armazene os segredos em um grupo de variáveis do Azure DevOps:
   • Configurações do Projeto → Pipelines → Biblioteca → Novo grupo de variáveis (por exemplo, uipath-prod).
   • Adicione UIPATH_CLIENT_ID e UIPATH_CLIENT_SECRET — marque ambos como secretos (ícone de cadeado).
   • Opcionalmente, adicione UIPATH_TENANT (não é um segredo).
3. Vincule o grupo de variáveis ao pipeline (consulte o bloco variables abaixo).
4. Provisione um projeto do Test Manager e um conjunto de testes (se você quiser o estágio de teste). Você precisará do TEST_SET_KEY (formato PROJECT:42) e PROJECT_KEY. Consulte Como fazer: executar testes a partir da CLI.

azure-pipelines.yml

trigger:
  branches:
    include: [ main ]

pr:
  branches:
    include: [ main ]

variables:
- group: uipath-prod           # contains UIPATH_CLIENT_ID, UIPATH_CLIENT_SECRET
- name:  CLI_VERSION
  value: '1.0.0'
- name:  NODE_VERSION
  value: '20.x'
- name:  SOLUTION_NAME
  value: 'my-solution'
- name:  SOLUTION_DIR
  value: '$(Build.SourcesDirectory)/my-solution'
- name:  OUTPUT_DIR
  value: '$(Build.ArtifactStagingDirectory)'
- name:  SOLUTION_VERSION
  value: '1.2.0-ci.$(Build.BuildId)'

# Path where npm places globally-installed packages. Used to cache the CLI + tools.
- name:  NPM_GLOBAL_CACHE
  value: '$(HOME)/.npm-global/lib/node_modules'

stages:

- stage: Build
  displayName: 'Pack the Solution'
  jobs:
  - job: pack
    pool:
      vmImage: 'ubuntu-latest'
    steps:

    - task: NodeTool@0
      displayName: 'Use Node.js $(NODE_VERSION)'
      inputs:
        versionSpec: $(NODE_VERSION)

    - task: Cache@2
      displayName: 'Cache npm global (@uipath/cli)'
      inputs:
        key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
        path: $(NPM_GLOBAL_CACHE)

    - script: |
        set -euo pipefail
        mkdir -p "$HOME/.npm-global"
        npm config set prefix "$HOME/.npm-global"
        export PATH="$HOME/.npm-global/bin:$PATH"
        echo "##vso[task.prependpath]$HOME/.npm-global/bin"

        if ! command -v uip >/dev/null; then
          npm install -g "@uipath/cli@$(CLI_VERSION)"
        fi

        uip --version
      displayName: 'Install UiPath CLI'

    - script: |
        set -euo pipefail
        uip solution pack "$(SOLUTION_DIR)" "$(OUTPUT_DIR)" \
          --name "$(SOLUTION_NAME)" \
          --version "$(SOLUTION_VERSION)"
      displayName: 'Pack Solution'

    - publish: '$(OUTPUT_DIR)'
      artifact: solution-zip
      displayName: 'Publish artifact'

- stage: Deploy
  displayName: 'Publish to feed and deploy to Orchestrator'
  dependsOn: Build
  jobs:
  - deployment: deploy
    environment: 'uipath-prod'      # Azure DevOps environment — gates / approvals live here
    pool:
      vmImage: 'ubuntu-latest'
    strategy:
      runOnce:
        deploy:
          steps:

          - task: NodeTool@0
            displayName: 'Use Node.js $(NODE_VERSION)'
            inputs:
              versionSpec: $(NODE_VERSION)

          - task: Cache@2
            displayName: 'Cache npm global (@uipath/cli)'
            inputs:
              key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
              path: $(NPM_GLOBAL_CACHE)

          - script: |
              set -euo pipefail
              mkdir -p "$HOME/.npm-global"
              npm config set prefix "$HOME/.npm-global"
              export PATH="$HOME/.npm-global/bin:$PATH"
              echo "##vso[task.prependpath]$HOME/.npm-global/bin"

              if ! command -v uip >/dev/null; then
                npm install -g "@uipath/cli@$(CLI_VERSION)"
              fi
            displayName: 'Install UiPath CLI'

          - script: |
              set -euo pipefail
              uip login \
                --client-id env.UIPATH_CLIENT_ID \
                --client-secret env.UIPATH_CLIENT_SECRET \
                --tenant "$UIPATH_TENANT"
            displayName: 'Authenticate'
            env:
              UIPATH_CLIENT_ID:     $(UIPATH_CLIENT_ID)
              UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)
              UIPATH_TENANT:        $(UIPATH_TENANT)

          - download: current
            artifact: solution-zip

          - script: |
              set -euo pipefail
              ARTIFACT=$(find "$(Pipeline.Workspace)/solution-zip" -maxdepth 1 -name "*.zip" | head -1)
              uip solution publish "$ARTIFACT"
            displayName: 'Publish to tenant feed'

          - script: |
              set -euo pipefail
              uip solution deploy run \
                --name "$(SOLUTION_NAME)-$(Build.BuildId)" \
                --package-name "$(SOLUTION_NAME)" \
                --package-version "$(SOLUTION_VERSION)" \
                --folder-name MySolution \
                --folder-path Shared
            displayName: 'Deploy to Orchestrator'

- stage: Test
  displayName: 'Run Test Manager suite'
  dependsOn: Deploy
  condition: and(succeeded(), ne(variables['TEST_SET_KEY'], ''))
  jobs:
  - job: test
    pool:
      vmImage: 'ubuntu-latest'
    steps:

    - task: NodeTool@0
      displayName: 'Use Node.js $(NODE_VERSION)'
      inputs:
        versionSpec: $(NODE_VERSION)

    - task: Cache@2
      displayName: 'Cache npm global (@uipath/cli)'
      inputs:
        key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
        path: $(NPM_GLOBAL_CACHE)

    - script: |
        set -euo pipefail
        export PATH="$HOME/.npm-global/bin:$PATH"
        echo "##vso[task.prependpath]$HOME/.npm-global/bin"
        if ! command -v uip >/dev/null; then
          npm install -g "@uipath/cli@$(CLI_VERSION)"
        fi

        uip login \
          --client-id env.UIPATH_CLIENT_ID \
          --client-secret env.UIPATH_CLIENT_SECRET \
          --tenant "$UIPATH_TENANT"
      displayName: 'Install + authenticate'
      env:
        UIPATH_CLIENT_ID:     $(UIPATH_CLIENT_ID)
        UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)
        UIPATH_TENANT:        $(UIPATH_TENANT)

    - script: |
        set -euo pipefail

        EXECUTION_ID=$(uip tm testsets run \
          --test-set-key "$TEST_SET_KEY" \
          --output-filter "Data.ExecutionId" \
          --output plain)

        echo "started execution $EXECUTION_ID"

        if ! uip tm wait \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY" \
          --timeout 1800; then
          code=$?
          case "$code" in
            2) echo "##vso[task.logissue type=error]test run did not finish within 30 minutes"; exit 2 ;;
            *) echo "##vso[task.logissue type=error]wait failed (exit $code)"; exit "$code" ;;
          esac
        fi

        uip tm report get \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY"

        FAILED=$(uip tm report get \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY" \
          --output-filter "Data.Failed" \
          --output plain)

        if [ "$FAILED" -gt 0 ]; then
          echo "##vso[task.logissue type=error]$FAILED test case(s) failed"
          exit 1
        fi
      displayName: 'Launch, wait, verify'
      env:
        TEST_SET_KEY: $(TEST_SET_KEY)
        PROJECT_KEY:  $(PROJECT_KEY)

Tutorial

Estágio 1 — Criar

• NodeTool@0 fixe o Node.js na versão 20. Fixar em um importante; a CLI requer 18+.
• Cache@2 armazena em cache o diretório global node_modules npm. A chave de cache inclui $(CLI_VERSION) para que um aumento de versão invalide corretamente.
• Instalar o prefixo global do npm para $HOME/.npm-global (não é necessário sudo ), prefixa-o ao PATH e — somente se o cache tiver perdido — instala @uipath/cli. A primeira invocação de um comando de ferramenta (uip solution …, uip tm …) instala automaticamente essa ferramenta, portanto, nenhum uip tools install explícito é necessário. Consulte Instalação do UiPath CLI — CI/CD e Padrões de script — fixar versões.
• A etapa Empacotar invoca uip solution pack com um --version explícito (nunca confie no padrão 1.0.0 no CI).
• publish: ... carrega todo o $(OUTPUT_DIR) como um artefato de pipeline chamado solution-zip para que o estágio de implantação possa consumi-lo. A publicação do diretório em vez de um nome de arquivo codificado mantém a receita estável entre alterações na convenção de nomenclatura da CLI.

Estágio 2 — Implantar

Usa um trabalho de implantação vinculado a um ambiente nomeado. Os ambientes são onde você configura portas e aprovações no Azure DevOps — o próprio YAML permanece simples.

• Reinstala a CLI (o cache deve atingir no segundo estágio da mesma execução).
• usa o prefixo uip login para o ID e o segredo env.VAR_NAME cliente. O bloco env: no nível da etapa mapeia $(UIPATH_CLIENT_ID) (do grupo de variáveis) para a variável de ambiente real UIPATH_CLIENT_ID que o sinalizador resolve. Não passe o segredo literalmente na linha de comando (--client-secret "$(UIPATH_CLIENT_SECRET)") — isso o vaza para o log de compilação e a saída de ps . A funcionalidade de prefixo env. está documentada na Autenticação — o prefixo env.var_NAME.
• download: current extrai o artefato solution-zip do Estágio 1 para $(Pipeline.Workspace)/solution-zip.
• uip solution publish carrega o .zip para o feed do tenant.
• uip solution deploy run cria a implantação. --name usa $(Build.BuildId) para que cada execução seja identificável e as reimplantações não ultrapassarem o registro de implantação umas das outras.

Estágio 3 — Teste

Execução apenas se TEST_SET_KEY estiver definido no nível do grupo de variáveis — a proteção de condition: ignora o estágio corretamente se você não tiver um pacote de testes configurado.

O bloco de shell é o lançamento canônico → aguardar → verificar fluxo de Como fazer: executar testes a partir da CLI:

1. uip tm testsets run inicia a execução e retorna um ExecutionId.
2. uip tm wait bloqueia até que a execução atinja um estado terminal (saída 2 significa tempo limite, não falha de autenticação — uma reutilização específica do domínio do slot de código de saída).
3. uip tm report get lê Data.Failed; a etapa falha com ##vso[task.logissue type=error] então o resultado aparece claramente na interface gráfica do Azure DevOps.

Variações comuns

Promover em ambientes

Vincule dois grupos de variáveis — uipath-stage e uipath-prod — e transforme cada um em um trabalho deployment: separado. Use portas/aprovações específicas do ambiente para decidir quando o produto é executado:

- stage: DeployStage
  dependsOn: Build
  jobs:
  - deployment: deploy-stage
    variables: [ { group: uipath-stage } ]
    environment: 'uipath-stage'
    # …same steps as above, but with stage's tenant

- stage: DeployProd
  dependsOn: DeployStage
  jobs:
  - deployment: deploy-prod
    variables: [ { group: uipath-prod } ]
    environment: 'uipath-prod'    # attach a manual approval gate here
    # …same steps as above

Cobertura mais profunda em Como fazer: empacotar e publicar uma Solução — promover um pacote entre os tenants.

Reverter

O Azure DevOps não reverte automaticamente; adicione um estágio manual que reimplanta a versão anterior:

- stage: Rollback
  dependsOn: []                   # run on demand, not from Deploy
  jobs:
  - job: rollback
    pool: { vmImage: 'ubuntu-latest' }
    steps:
    # …install + auth…
    - script: |
        uip solution deploy run \
          --name "$(SOLUTION_NAME)-rollback" \
          --package-name "$(SOLUTION_NAME)" \
          --package-version "$(ROLLBACK_VERSION)" \
          --folder-name MySolution \
          --folder-path Shared
      displayName: 'Re-deploy previous version'

Passe ROLLBACK_VERSION no tempo da fila. Para reversão destrutiva (desinstalar + excluir artefato), consulte Instruções: empacotar e publicar uma solução — reverter.

Ignorar testes

Para executar sem o estágio de teste, exclua o bloco de estágio Test (ou deixe TEST_SET_KEY não definido — o condition: no estágio o ignorará).

armadilhas comuns

• prefixoenv. versus segredo literal. Sempre --client-secret env.UIPATH_CLIENT_SECRET, nunca --client-secret "$(UIPATH_CLIENT_SECRET)". A forma literal incorpora o valor na linha de comando renderizada. Consulte o aviso de autenticação.
• ##vso[task.setvariable] não é necessário para a resolução env. — env: na etapa expõe a variável diretamente.
• O bash multilinha precisa de set -euo pipefail no topo de cada bloco script: . Sem ele, pack pode falhar enquanto as etapas posteriores continuam em execução. Consulte Padrões de script — opções estritas de shell.
• As ocorrências de cache não são garantidas. Sempre envolva os comandos de instalação em if ! command -v uip para que o pipeline se corrija quando o cache estiver vazio.

Veja também

• Como fazer: implantar no Orchestrator a partir do CI — orientação independente de plataforma.
• Como fazer: empacotar e publicar uma Solução — controle de versão e rollback.
• Como fazer: executar testes a partir da CLI — o iniciar → aguardar → verificar padrão em profundidade.
• Receita de CI/CD: GitHub Actions, Jenkins, GitLab CI — o mesmo pipeline em outras plataformas.