Como fazer: empacotar e publicar uma solução

Esta página começa onde seu primeiro pipeline para. Ele pressupõe que você já tem o fluxo de três comandos funcionando em um único tenant e agora deseja enviar a mesma Solução em dev → estágio → prod, fixar versões para reprodutibilidade e saber exatamente como reverter uma versão ruim.

Se você ainda não empacotado uma Solução de ponta a ponta, leia Seu primeiro pipeline primeiro — tudo aqui é construído em uip solution pack / publish / deploy run.

O que este guia abrange

• Uma regra de controle de versão que funciona bem com o feed do Orchestrator.
• Promove o mesmo pacote por meio de vários tenants sem reempacotamento.
• Fixar a CLI e suas ferramentas para que cada compilação seja reprodutível.
• Revertendo uma versão quebrada com uip solution packages delete e uip solution deploy uninstall.

Escolha uma versão e congele-a

uip solution pack --version o nome do arquivo .zip e o packageVersion que cada etapa subsequente consome. O padrão é 1.0.0; um pipeline real deve passá-lo explicitamente.

O versionamento semântico (MAJOR.MINOR.PATCH) é o esquema que o feed do Orchestrator classifica melhor. Duas regras concretas fazem a diferença entre um histórico limpo e um não classificável:

1. Nunca reutilize uma versão. uip solution publish rejeita um par name+version que já existe no feed. Trate uma publicação rejeitada como um bug de compilação, não como algo a ser "corrigido" executando pack novamente.
2. Use metadados de compilação, não carimbos de data/hora no núcleo da versão. Prefira 1.2.0-rc.3 a 1.2.0.20260424. A primeira classifica corretamente no feed; o último é tecnicamente válido semver, mas mais difícil de ler rapidamente.

Uma configuração típica de CI:

# Build number from the pipeline, tag from git, combined for a valid pre-release
VERSION="1.2.0-ci.${BUILD_NUMBER}"

uip solution pack ./my-solution ./dist \
  --name my-solution \
  --version "$VERSION"

uip solution publish "./dist/my-solution.${VERSION}.zip"

O caminho .zip é determinístico (<outputDir>/<name>.<version>.zip) — consulte uip solution pack — para que os scripts possam computá-lo sem analisar JSON.

Promover um pacote entre os tenants

Empacote e publique uma vez por versão e, em seguida, reimplante o mesmo artefato em cada tenant. A reempacotamento por ambiente arrisca a descompassos; a republicação da mesma versão também é idempotente por (name, version), portanto, se você publicar duas vezes por engano, nada será interrompido. Ainda assim, uma compilação = uma publicação é o contrato mais limpo.

uip solution publish e cada subcomando uip solution deploy * aceita --tenant <tenant-name> (curto: -t) para substituir o tenant selecionado pela sessão ativa. Para um trabalho de promoção de CI:

VERSION="$1"   # e.g. 1.2.0-ci.456

for tenant in dev stage prod; do
  uip solution publish "./dist/my-solution.${VERSION}.zip" --tenant "$tenant"

  uip solution deploy run \
    --name "my-solution-${tenant}" \
    --package-name my-solution \
    --package-version "$VERSION" \
    --folder-name MySolution \
    --folder-path Shared \
    --tenant "$tenant"
done

Duas observações:

• publish é idempotente por tenant. A publicação do mesmo (name, version) duas vezes retorna o PackageVersionKey existente em vez de duplicar — consulte uip solution publish.
• Os nomes de implantação devem ter o escopo de tenant. Usar my-solution-prod em vez de my-solution torna uip solution deploy list legível e evita chamadas deploy uninstall acidentais entre ambientes. --name identifica o registro de implantação, não a pasta.

Parametrizar a configuração por ambiente

Se sua solução tiver recursos (filas, ativos) que diferem por tenant, gere o arquivo de configuração uma vez e edite-o por ambiente com deploy config set:

uip solution deploy config get my-solution --package-version "$VERSION" -d ./deploy-config.json

# Production uses a bigger retry count
uip solution deploy config set ./deploy-config.json MyQueue maxNumberOfRetries 5

uip solution deploy run \
  --name my-solution-prod \
  --package-name my-solution \
  --package-version "$VERSION" \
  --folder-name MySolution \
  --folder-path Shared \
  --config-file ./deploy-config.json \
  --tenant prod

Transmita um recurso do Orchestrator existente em vez de um recém-criado com deploy config link:

uip solution deploy config link ./deploy-config.json MyQueue \
  --name SharedProductionQueue \
  --folder-path "Shared/Production"

Fixar a CLI e suas ferramentas

Os pipelines reprodutíveis fixadam todas as ferramentas das quais dependem. A CLI é distribuída no npm como @uipath/cli; uip solution … é fornecido por @uipath/solution-tool. Ambos seguem semver.

# Pin the CLI exactly
npm install -g @uipath/cli@1.0.0

# Pre-install tools explicitly so the first command is not slower than the rest
uip tools install @uipath/solution-tool @uipath/orchestrator-tool

As versões da ferramenta padrão rastreiam a linha MAJOR.MINOR da CLI, portanto, fixar a CLI isoladamente geralmente é suficiente. Para obter reprodutibilidade rigorosa por patch, fixe a ferramenta também:

uip tools install @uipath/solution-tool@1.0.2

Consulte Padrões de script — fixar versões no CI e Instalar o UiPath CLI — CI/CD para a história completa.

Reverter

A interrupção da produção é rara; revertendo quando isso acontece. Há dois níveis de reversão — reimplantar uma versão conhecida (rápido) e excluir o artefato ruim (limpo).

Rápido: reimplantar a versão anterior

Se a implantação incorreta estiver ativa, instale a versão anterior sobre ela em vez de desinstalar primeiro. O nome de implantação permanece o mesmo; apenas --package-version alterações:

uip solution deploy run \
  --name my-solution-prod \
  --package-name my-solution \
  --package-version 1.1.9 \
  --folder-name MySolution \
  --folder-path Shared \
  --tenant prod

Esse é o caso comum. O Orchestrator reativa a nova implantação para a chave de configuração e deixa os recursos da pasta intactos.

Limpo: desinstala a implantação

Se a solução provisionou recursos (filas, ativos, gatilhos) que você não deseja, chame uip solution deploy uninstall:

uip solution deploy uninstall my-solution-prod --tenant prod

Isso remove todos os recursos provisionados e a pasta da Solução. É uma operação destrutiva — confirme o nome da implantação com deploy list antes de executá-la, especialmente em um loop sobre tenants.

Descontinuar o artefato

Quando nada fizer referência a uma versão ruim, remova-a do feed do tenant com uip solution packages delete:

uip solution packages delete my-solution 1.2.0-ci.456 --tenant prod

Não há exclusão reversível; isso é permanente. Mantenha a exclusão em uma janela pequena — o comando aceita exatamente uma packageVersion de cada vez, portanto, a execução de scripts de limpezas em massa requer um padrão list → filter → xargs . Consulte a referência packages delete para obter um exemplo completo.

Verificando o que você tem

Antes de qualquer uma das opções acima, obtenha a verdade fundamental:

# What is in the feed?
uip solution packages list --take 50 \
  --output-filter "Data[?packageName=='my-solution']"

# What is deployed?
uip solution deploy list --folder-path Shared --take 50

Fragmento pronto para CI

Combinando as etapas — um script de shell que qualquer sistema de CI pode executar como está:

#!/usr/bin/env bash
set -euo pipefail

VERSION="$1"                          # e.g. 1.2.0-ci.456
SOLUTION_DIR="./my-solution"
OUT_DIR="./dist"

# 1. Log in (External App in CI)
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT_DEV"

# 2. Pack once
uip solution pack "$SOLUTION_DIR" "$OUT_DIR" \
  --name my-solution \
  --version "$VERSION"

PKG="${OUT_DIR}/my-solution.${VERSION}.zip"

# 3. Publish + deploy to each tenant
for env_name in dev stage prod; do
  tenant_var="UIPATH_TENANT_$(echo "$env_name" | tr a-z A-Z)"
  tenant="${!tenant_var}"

  uip solution publish "$PKG" --tenant "$tenant"
  uip solution deploy run \
    --name "my-solution-${env_name}" \
    --package-name my-solution \
    --package-version "$VERSION" \
    --folder-name MySolution \
    --folder-path Shared \
    --tenant "$tenant"
done

Com, set -euo pipefail falha anula o loop no tenant com falha. Os tenants posteriores não são afetados — a promoção parcial pode ser executada novamente ou revertida explicitamente.

Próximas Etapas

• Como fazer: implantar no Orchestrator a partir do CI — agnóstico de plataforma aprofundado sobre autenticação, cache e pré-instalação de ferramentas.
• Receitas de CI/CD — pipelines copiáveis e coláveis para Azure DevOps, GitHub Actions, Jenkins, GitLab.
• Referênciauip solution — cada subcomando.
• Padrões de script — ramificação do código de saída, pipelines idempotentes, nova tentativa de autenticação.