Como fazer: empacotar e publicar uma solução

Empacote e publique uma solução da UiPath em ambientes de desenvolvimento, estágio e produção com orientação de fixar versão e reverter.

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.

Para um trabalho de promoção de CI, alterne o tenant da sessão ativa entre iterações com uip login tenant set <tenant> e, em seguida, execute publish/deploy run contra o tenant ao qual a sessão está atualmente associada:

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

for tenant in dev stage prod; do
  uip login tenant set "$tenant"

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

  uip solution deploy run \
    --name "my-solution-${tenant}" \
    --package-name my-solution \
    --package-version "$VERSION" \
    --folder-name MySolution \
    --parent-folder-path Shared
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 login tenant set prod

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 \
  --parent-folder-path Shared \
  --config-file ./deploy-config.json

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"

Atualizar uma implantação para uma nova versão

deploy run cria uma nova implantação em uma nova pasta — executá-la novamente com o mesmo --name não atualiza a implantação existente no local; ele falha (a menos que você aprove -y, --yes, que instala uma segunda cópia independente ao lado da primeira). Para mover uma implantação ao vivo para uma versão de pacote mais recente, use uip solution deploy upgrade em vez disso. Ele preserva a pasta da implantação, os recursos provisionados e qualquer configuração já definida neles (por exemplo, o segredo de um ativo de credencial).

Primeiro, encontre a chave da implantação com deploy list:

uip login tenant set prod

DEPLOYMENT_KEY=$(uip solution deploy list \
  --output-filter "Data[?Name=='my-solution-prod'] | [0].Key" --output plain)

Em seguida, atualize-o:

uip solution deploy upgrade "$DEPLOYMENT_KEY" --version 1.3.0

Apenas a versão publicada mais recente é suportada como um destino de atualização hoje. Passe --no-wait para retornar assim que a atualização for aceita em vez de esperar que ela seja finalizada. A mesma mecanismo funciona ao contrário para desfazer uma versão ruim — consulte Reverter.

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: mova a implantação de volta para a versão anterior

Se a implantação ruim estiver ativa, mova-a de volta para a última versão conhecida com deploy upgrade em vez de desinstalar primeiro — observe que deploy upgrade é compatível apenas com a versão mais recente publicada como um destino hoje, então esse caminho assume que a versão anterior é (ou foi republicado como) o mais recente no feed:

uip login tenant set prod

DEPLOYMENT_KEY=$(uip solution deploy list \
  --output-filter "Data[?Name=='my-solution-prod'] | [0].Key" --output plain)

uip solution deploy upgrade "$DEPLOYMENT_KEY" --version 1.1.9

Esse é o caso comum. Ela deixa os recursos provisionados da pasta intactos e reutiliza a configuração existente.

Limpo: desinstala a implantação

Se a solução provisionou recursos (filas, ativos, gatilhos) que você não deseja, chame uip solution deploy uninstall — ele requer -y, --yes pois é irreversível:

uip login tenant set prod

uip solution deploy uninstall my-solution-prod --yes

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 login tenant set prod

uip solution packages delete my-solution 1.2.0-ci.456 --yes

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 --limit 50 \
  --output-filter "Data[?packageName=='my-solution']"

# What is deployed?
uip solution deploy list --folder-path Shared --limit 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 login tenant set "$tenant"

  uip solution publish "$PKG"
  uip solution deploy run \
    --name "my-solution-${env_name}" \
    --package-name my-solution \
    --package-version "$VERSION" \
    --folder-name MySolution \
    --parent-folder-path Shared
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.