Como fazer: implantar no Orchestrator a partir do CI

Esta página abrange o que cada pipeline de CI implantando uma solução da UiPath precisa, independentemente de você executar no Azure DevOps, GitHub Actions, Jenkins ou GitLab: autenticação, cache, pré-instalação da ferramenta e atribuição de versão. A sintaxe específica da plataforma reside nas páginas de receita — essa fornece as partes móveis para que você possa ler qualquer uma delas com confiança.

A forma de um bom pipeline de CI

Um pipeline de produção que envia uma Solução sempre tem os mesmos cinco estágios:

1. Configure o Node.js (versão 18 ou posterior).
2. Instale @uipath/cli em uma versão fixada.
3. Pré-instale as ferramentas que você usará (para que a uip chamada não seja mais lenta que as demais).
4. Autentique com um aplicativo externo usando o prefixo env. para segredos.
5. Empacotar, publicar, implantar — e, opcionalmente, testar.

O estágio 4 é aquele que mais varia entre as plataformas, porque a sintaxe do segredo é específica da plataforma. Os estágios 1–3 e 5 são quase idênticos em todos os lugares.

Autenticação: aplicativo externo + ambiente. prefixo

Em um ambiente sem periféricos, você se autentica com um Aplicativo Externo (credenciais do cliente). Consulte Autenticação — Fluxo 2 para saber como criar uma no portal da UiPath.

Armazene as credenciais no armazenamento secreto da sua plataforma (nunca no controle de origem, nunca em um arquivo env var simples). Passe-os para uip login com o prefixo especial env. :

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

O prefixo env.VAR_NAME informa uip para ler o valor da variável de ambiente VAR_NAME no runtime. Isso mantém o segredo fora do histórico de shell e listagens de processos — ao contrário de --client-secret "$UIPATH_CLIENT_SECRET", que se expande na linha de comando e pode vazar por meio de ps.

AVISO:

Não confie na leitura implícita de env-var. A configuração de UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET isoladamente, sem o sinalizador, não autenticará você — essa funcionalidade foi removida antes da CLI 1.0. Sempre passar o sinalizador; use env.VAR_NAME quando quiser que o valor resolvido a partir do ambiente.

Em seu pipeline, injetar os segredos no ambiente da etapa sob os nomes de variáveis exatas às quais você faz referência:

Plataforma	Sintaxe de segredo em YAML/Grooxy	Forma passada para a etapa
Ações do GitHub	${{ secrets.UIPATH_CLIENT_ID }} presente env:	UIPATH_CLIENT_ID: <value>
Azure DevOps	$(UIPATH_CLIENT_ID) de um grupo de variáveis em env:	UIPATH_CLIENT_ID: $(UIPATH_CLIENT_ID)
Jenkins	credentialsId: 'UIPATH_CLIENT_ID' Dentro de withCredentials	exportado como $UIPATH_CLIENT_ID
GitLab CI	UIPATH_CLIENT_ID Variável de CI/CD, marcada como Protegida+Mascarada	$UIPATH_CLIENT_ID presente script

Em todos os casos, o próprio comando uip login parece idêntico — --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET. Apenas o modo como a var de ambiente chega na etapa muda.

Armazenamento da sessão

persiste a sessão dentro de .uipath/ uip login Na maioria dos executores de CI, o diretório de trabalho já é sem estado, então a sessão termina com o trabalho — que é o comportamento desejado. Se seu executor for persistente, remova a sessão com uip logout no final do trabalho ou defina --file como um caminho local do trabalho. Consulte Sessões e credenciais.

Várias organizações em um pipeline

Uma sessão contém uma organização e um tenant por vez. Para segmentar diferentes organizações UiPath do mesmo pipeline — por exemplo, para promover uma solução de uma organização de compilação em uma organização de cliente — execute novamente uip login entre os dois blocos com um Aplicativo externo diferente. Cada logon substitui a sessão anterior.

Crie um aplicativo externo por organização (cada um com seus OR.* escopos). Armazene IDs de clientes e segredos no armazenamento secreto do pipeline sob nomes distintos:

set -euo pipefail

# --- Organization A ---
uip login \
  --client-id env.ORGA_CLIENT_ID \
  --client-secret env.ORGA_CLIENT_SECRET \
  --tenant Prod

uip or folders list
uip solution pack ./my-solution ./dist --version "$SOLUTION_VERSION"
uip solution publish "./dist/my-solution.$SOLUTION_VERSION.zip"

# --- Organization B — this overwrites the previous session ---
uip login \
  --client-id env.ORGB_CLIENT_ID \
  --client-secret env.ORGB_CLIENT_SECRET \
  --tenant Prod

uip solution publish "./dist/my-solution.$SOLUTION_VERSION.zip"
uip solution deploy run \
  --name "my-solution-$GIT_SHA" \
  --package-name my-solution \
  --package-version "$SOLUTION_VERSION" \
  --folder-name MySolution \
  --folder-path Shared

Mesmo padrão para diferentes tenants dentro de uma única organização — exceto que os tenants não precisam de um segundo login. Passe --tenant <name> em qualquer chamada uip or … para substituir o tenant da sessão para um único comando, sem autenticar novamente.

Observação:

Esse é um padrão serial . Cada uip login substitui a sessão armazenada, então apenas uma organização é acessível a qualquer momento. Se você precisar executar comandos em duas organizações simultaneamente (por exemplo, trabalhos de matriz paralela), dê a cada trabalho seu próprio executor ou seu próprio escopo --file / HOME — consulte Sessões e credenciais.

Ferramentas de pré-instalação para manter os tempos de compilação determinísticos

A CLI é enviada sem ferramentas pré-instaladas. A primeira vez que você executa um verbo de uma ferramenta desinstalada, uip o instala automaticamente a partir do npm — o que é bom em um laptop, mas adiciona de 5 a 10 segundos de latência ao primeiro comando em um executor de CI sem estado.

Instale as ferramentas que você usa antecipadamente, como uma etapa separada:

uip tools install @uipath/orchestrator-tool @uipath/solution-tool

Adicione @uipath/test-manager-tool quando você executa o Test Manager, @uipath/agent-tool quando você implanta Agentes, @uipath/resource-tool quando você gerencia ativos/filas/buckets fora de uma Solução. Consulte a referência de ferramentas para obter a lista completa.

A instalação automática é um no-op quando a ferramenta já está instalada, portanto, a etapa de pré-instalação é a única alteração de comportamento de que você precisa — nada mais no seu pipeline precisa saber sobre isso.

Observação:

CI=true não desabilita a instalação automática. Não há chave env-var; a pré-instalação é a única maneira de evitá-lo. Consulte Instalação do UiPath CLI — Controle da instalação automática da ferramenta.

Armazene em cache o diretório global npm

Os executores de CI que reinstalam @uipath/cli em cada trabalho gastam de 20 a 40 segundos de download e descompactação. O cache do diretório global node_modules npm transforma isso em uma ocorrência de cache — geralmente menos de um segundo.

O diretório para armazenar em cache é o relatado por npm root -g (normalmente ~/.npm-global/lib/node_modules no Linux/macOS, %APPDATA%\npm\node_modules no Windows). Codifique o cache na versão da CLI que você fixou, para que um aumento de versão invalide o cache corretamente:

Plataforma	Mecanismo de cache
Ações do GitHub	actions/cache com path: ~/.npm-global/lib/node_modules e key: uip-${{ version }}-${{ runner.os }}
Azure DevOps	Cache@2 chaveado na variável de versão
Jenkins	O plug-in do Job Cache ou uma pasta de espaço de trabalho gerenciada manualmente
GitLab CI	Bloco cache: de nível superior com key: uip-$CLI_VERSION

Quando o cache for atingido, você pode ignorar tanto npm install -g @uipath/cli quanto uip tools install — o executável uip e suas ferramentas já estão no PATH. Um pequeno bash guard faz isso de forma limpa:

if ! command -v uip >/dev/null; then
  npm install -g "@uipath/cli@${CLI_VERSION}"
  uip tools install @uipath/orchestrator-tool @uipath/solution-tool
fi

O YAML/Grooty Concreta para cada plataforma está nas páginas de receita.

Fixe versões para reprodutibilidade

Os pipelines reprodutíveis fixadam tudo. Quatro versões importam:

• Node.js — fixe o principal (20.x em setup-node das Ações do GitHub, versionSpec: '20.x' no Azure DevOps).
• @uipath/cli fixe exatamente (@1.0.0), não um intervalo.
• Ferramentas — opcional. Por padrão, eles rastreiam a linha MAJOR.MINOR da CLI; fixe apenas se você precisar de reprodutibilidade rigorosa no nível do patch (@uipath/solution-tool@1.0.2).
• A versão de sua própria solução — passe --version para uip solution pack explicitamente. Nunca confie no padrão 1.0.0 no CI.

# Pin these once at the top of the pipeline; reuse below
CLI_VERSION="1.0.0"
SOLUTION_VERSION="1.2.0-ci.${BUILD_NUMBER}"

npm install -g "@uipath/cli@${CLI_VERSION}"
uip tools install @uipath/solution-tool @uipath/orchestrator-tool

uip solution pack ./my-solution ./dist --version "$SOLUTION_VERSION"

O caminho é ./dist/my-solution.${SOLUTION_VERSION}.zip .zip , então as etapas subsequentes podem construí-lo sem analisar a saída uip solution pack JSON.

Consulte Padrões de script — fixar versões no CI para as regras de atribuição de ferramentas em mais profundidade.

O bloco de implantação mínimo

Toda plataforma se resume a isso:

set -euo pipefail

# Authenticate
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

# Pack
uip solution pack ./my-solution ./dist \
  --name my-solution \
  --version "$SOLUTION_VERSION"

# Publish
uip solution publish "./dist/my-solution.${SOLUTION_VERSION}.zip"

# Deploy
uip solution deploy run \
  --name "my-solution-${ENVIRONMENT}" \
  --package-name my-solution \
  --package-version "$SOLUTION_VERSION" \
  --folder-name MySolution \
  --folder-path Shared

faz com que o script falhe rapidamente: set -euo pipefail anula em qualquer saída diferente de zero, -u captura variáveis indefinidas -e -o pipefail propaga falhas por meio de pipes. Esse é o padrão que toda receita nesta documentação usa. Consulte Padrões de script — opções estritas de shell.

Opcional: execute testes após a implantação

Se a Solução incluir um conjunto de testes, inicie → aguarde → verifique-o antes de marcar o pipeline verde. O padrão de três etapas é importante: uip tm testsets run sai 0 assim que a execução é enfileirada, não quando os testes são aprovados — então você precisa uip tm wait para bloquear e uip tm report get para ler o veredicto.

Consulte Como fazer: executar testes a partir da CLI para obter o padrão completo com tratamento de erros.

Processamento de reautenticação no meio do pipeline

Os tokens de acesso podem expirar durante pipelines de longa duração. A página Padrões de script tem o padrão de nova tentativa canônico: ramificar no código de saída 2 (AuthenticationError), executar novamente uip login, tentar novamente uma vez, caso contrário, falhar. Na maioria dos pipelines de CI, isso é desnecessário — os trabalhos são curtos o suficiente para que o token de login inicial dure toda a execução — mas conjuntos de testes longos ou loops de promoção de vários tenants podem se beneficiar disso.

Receitas da plataforma

Para pipelines completos e coláveis na sintaxe nativa da sua plataforma:

• Receita de CI/CD: Azure DevOps
• Receita de CI/CD: ações do GitHub
• Receita de CI/CD: Jenkins
• Receita de CI/CD: GitLab CI

Cada receita mostra o pipeline completo (instalar → autenticação → empacotar → publicar → implantar → teste), a conexão secreta, uma entrada de cache e variações para fixar versões e executar testes.

Veja também

• Seu primeiro pipeline — o fluxo mínimo de três comandos.
• Como fazer: empacotar e publicar uma solução — regra de versionamento, promoção para vários ambientes, rollback.
• Autenticação — os três fluxos e quando usar cada um.
• Padrões de script — códigos de saída, nova tentativa, filtragem JSON.
• Instalação do UiPath CLI — CI/CD — detalhes de pré-instalação e cache.