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.

For a CI promotion job, switch the active session's tenant between iterations with uip login tenant set <tenant>, then run publish/deploy run against whichever tenant the session is currently bound to:

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 always creates a new deployment in a new folder — running it again with the same --name does not update the existing deployment in place; it fails (unless you pass -y, --yes, which installs a second, independent copy alongside the first). To move a live deployment to a newer package version in place, use uip solution deploy upgrade instead. It preserves the deployment's folder, provisioned resources, and any configuration already set on them (for example a credential asset's secret).

First find the deployment's key with deploy list:

uip login tenant set prod

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

Then upgrade it:

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

Only the latest published version is supported as an upgrade target today. Pass --no-wait to return as soon as the upgrade is accepted instead of waiting for it to finish. The same mechanic works in reverse to undo a bad release — see Rollback.

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).

Fast: move the deployment back to the previous version

If the bad deployment is live, move it back to the last known-good version with deploy upgrade instead of uninstalling first — note that deploy upgrade only supports the latest published version as a target today, so this path assumes the previous version is (or has been republished as) the newest one in the 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

This is the common case. It leaves the folder's provisioned resources intact and reuses the existing configuration.

Limpo: desinstala a implantação

If the Solution provisioned resources (queues, assets, triggers) that you do not want, call uip solution deploy uninstall — it requires -y, --yes since it is irreversible:

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.