Tutorial: implementar en Orchestrator desde CI

Esta página cubre lo que necesita cada proceso de CI que implementa una solución de UiPath, independientemente de si se ejecuta en Azure DevOps, GitHub Actions, Jenkins o GitLab: autenticación, almacenamiento en caché, preinstalación de herramientas y fijación de versiones. La sintaxis específica de la plataforma se encuentra en las páginas de recetas : esta te proporciona las partes móviles para que puedas leer cualquiera de ellas con confianza.

La forma de un buen proceso de CI

Un proceso de producción que envía una solución siempre tiene las mismas cinco etapas:

1. Configura Node.js (versión 18 o posterior).
2. Instala @uipath/cli en una versión anclada.
3. Preinstala las herramientas que utilizarás (para que la primera llamada uip no sea más lenta que el resto).
4. Autentica con una aplicación externa utilizando el prefijo env. para secretos.
5. Empaqueta, publica, implementa y, opcionalmente, prueba.

La etapa 4 es la que más varía entre plataformas, porque la sintaxis secreta es específica de la plataforma. Las etapas 1–3 y 5 son casi idénticas en todas partes.

Autenticación: aplicación externa + env. Prefijo

En un entorno headless, te autenticas con una aplicación externa (credenciales de cliente). Consulta Autenticación: flujo 2 para saber cómo crear uno en el portal de UiPath.

Almacena las credenciales en el almacén de secretos de tu plataforma (nunca en el control de origen, nunca en un archivo env var simple). Pásalas a uip login con el prefijo especial env. :

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

El prefijo env.VAR_NAME le dice a uip que lea el valor de la variable de entorno VAR_NAME en tiempo de ejecución. Esto mantiene el secreto fuera del historial del shell y de los listados de procesos, a diferencia de --client-secret "$UIPATH_CLIENT_SECRET", que se expande en la línea de comandos y puede filtrarse a través de ps.

ADVERTENCIA:

No confíes en la lectura implícita de env-var. Configurar UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET solo, sin el marcador, no te autenticará: esa característica se eliminó antes de CLI 1.0. Pasar siempre el marcador; utiliza env.VAR_NAME cuando quieras que el valor se resuelva desde el entorno.

En tu proceso, inyecta los secretos en el entorno del paso bajo los nombres de variables exactos a los que haces referencia:

Plataforma	Sintaxis secreta en YAML/Groovy	Forma pasada al paso
Acciones de GitHub	${{ secrets.UIPATH_CLIENT_ID }} en env:	UIPATH_CLIENT_ID: <value>
Azure DevOps	$(UIPATH_CLIENT_ID) de un grupo de variables en env:	UIPATH_CLIENT_ID: $(UIPATH_CLIENT_ID)
Jenkins	credentialsId: 'UIPATH_CLIENT_ID' Dentro withCredentials	exportado como $UIPATH_CLIENT_ID
CI de GitLab	UIPATH_CLIENT_ID Variable CI/CD, marcada como Protegida+Enmascarada	$UIPATH_CLIENT_ID en script

En todos los casos, el comando uip login en sí tiene un aspecto idéntico: --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET. Solo cambia la forma en que la variable de entorno llega al paso.

Almacenamiento de sesión

uip login persiste la sesión dentro de una carpeta .uipath/ . En la mayoría de los ejecutores de CI, el directorio de trabajo ya no tiene estado, por lo que la sesión finaliza con el trabajo, que es el comportamiento deseado. Si tu ejecutor es persistente, elimina la sesión con uip logout al final del trabajo o establece --file en una ruta local del trabajo. Consulta Sesiones y credenciales.

Varias organizaciones en un proceso

Una sesión contiene una organización y un tenant a la vez. Para apuntar a diferentes organizaciones de UiPath desde el mismo proceso, por ejemplo, para promocionar una solución de una organización de creación a una organización de cliente, vuelve a ejecutar uip login entre los dos bloques con una aplicación externa diferente. Cada inicio de sesión sobrescribe la sesión anterior.

Crea una aplicación externa por organización (cada una con sus propios ámbitos OR.* ). Almacena tanto los ID de cliente como los secretos en el almacén de secretos del proceso con nombres 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

El mismo patrón para diferentes tenants dentro de una sola organización, excepto que los tenants no necesitan un segundo inicio de sesión. Pasa --tenant <name> en cualquier llamada uip or … para anular el tenant de sesión para un solo comando, sin volver a autenticarte.

Nota:

Este es un patrón en serie . Cada uip login sobrescribe la sesión almacenada, por lo que solo se puede acceder a una organización en cualquier momento. Si necesitas ejecutar comandos en dos organizaciones simultáneamente (por ejemplo, trabajos de matriz paralela), asigna a cada trabajo su propio ejecutor o su propio ámbito --file / HOME — consulta Sesiones y credenciales.

Preinstale herramientas para mantener los tiempos de construcción deterministas

La CLI se envía sin herramientas preinstaladas. La primera vez que ejecutas un verbo desde una herramienta desinstalada, uip lo instala automáticamente desde npm, lo que está bien en un portátil, pero añade entre 5 y 10 segundos de latencia al primer comando en un ejecutor de CI sin estado.

Instala las herramientas que utilizas por adelantado, como un paso independiente:

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

Añade @uipath/test-manager-tool al ejecutar Test Manager, @uipath/agent-tool al implementar agentes, @uipath/resource-tool al gestionar activos/colas/depósitos fuera de una solución. Consulta la referencia de herramientas para ver la lista completa.

La instalación automática no es operativa cuando la herramienta ya está instalada, por lo que el paso de preinstalación es el único cambio de comportamiento que necesitas: nada más en tu proceso tiene que saberlo.

Nota:

CI=true no deshabilita la instalación automática. No hay conmutador env-var; la preinstalación es la única forma de evitarlo. Consulta Instalar UiPath CLI: controlar la instalación automática de la herramienta.

Almacenar en caché el directorio global npm

Los ejecutores de CI que reinstalan @uipath/cli en cada trabajo desperdician entre 20 y 40 segundos de descarga y descompresión. Almacenar en caché el directorio node_modules global de npm lo convierte en un acierto de caché, generalmente en menos de un segundo.

El directorio para almacenar en caché es el informado por npm root -g (normalmente ~/.npm-global/lib/node_modules en Linux/macOS, %APPDATA%\npm\node_modules en Windows). Clave la caché en la versión de CLI que anclas, para que un golpe de versión invalide la caché limpiamente:

Plataforma	Mecanismo de caché
Acciones de GitHub	actions/cache con path: ~/.npm-global/lib/node_modules y key: uip-${{ version }}-${{ runner.os }}
Azure DevOps	Cache@2 tecleado en la variable de versión
Jenkins	El complemento de Job Cacher o una carpeta de espacio de trabajo gestionada manualmente
CI de GitLab	Bloque cache: de nivel superior con key: uip-$CLI_VERSION

Cuando la caché llega, puedes omitir tanto npm install -g @uipath/cli como uip tools install : el ejecutable uip y sus herramientas ya están en PATH. Un pequeño bash guard hace esto limpiamente:

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

El YAML/Groovy concreto para cada plataforma se encuentra en las páginas de recetas.

Anclar versiones para reproducibilidad

Los procesos reproducibles fijan todo. Cuatro versiones importan:

• Node.js : fija la especialidad (20.x en setup-node de GitHub Actions, versionSpec: '20.x' en Azure DevOps).
• @uipath/cli — anclar exactamente (@1.0.0), no un rango.
• Herramientas : opcional. De forma predeterminada, realizan un seguimiento de la línea MAYOR.MENOR de CLI; pin solo si necesitas una reproducibilidad estricta en el nivel de parche (@uipath/solution-tool@1.0.2).
• La versión de tu propia solución : pasa --version a uip solution pack explícitamente. Nunca confíes en el valor predeterminado 1.0.0 en 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"

La ruta .zip es determinista (./dist/my-solution.${SOLUTION_VERSION}.zip), por lo que los pasos posteriores pueden construirla sin analizar la salida JSON uip solution pack .

Consulta Patrones de scripts: fijar versiones en CI para las reglas de fijación de herramientas en profundidad.

El bloque de implementación mínimo

Cada plataforma se reduce a esto:

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

set -euo pipefail hace que el script falle rápidamente: -e aborta en cualquier salida distinta de cero, -u captura variables indefinidas, -o pipefail propaga fallos a través de canalizaciones. Este es el patrón que utiliza cada receta de esta documentación. Consulta Patrones de scripts: opciones de shell estrictas.

Opcional: ejecutar pruebas después de la implementación

Si la solución incluye un conjunto de pruebas, inícialo → espera → verifícalo antes de marcar el proceso en verde. El patrón de tres pasos es importante: uip tm testsets run sale de 0 tan pronto como la ejecución está en cola, no cuando se pasan las pruebas, por lo que necesitas uip tm wait para bloquear y uip tm report get leer el veredicto.

Consulta Tutorial: ejecutar pruebas desde la CLI para ver el patrón completo con gestión de errores.

Gestionar la reautenticación en mitad del proceso

Los tokens de acceso pueden caducar durante procesos de larga duración. La página de patrones de scripting tiene el patrón de reintento canónico: rama en el código de salida 2 (AuthenticationError), volver a ejecutar uip login, reintentar una vez, fallar de lo contrario. En la mayoría de los procesos de CI esto es innecesario: los trabajos son lo suficientemente cortos como para que el token del inicio de sesión inicial dure toda la ejecución, pero las suites de prueba largas o los bucles de promoción de tenant múltiple pueden beneficiarse de ello.

Recetas de plataforma

Para obtener procesos completos que se pueden copiar y pegar en la sintaxis nativa de tu plataforma:

• Receta CI/CD: Azure DevOps
• Receta CI/CD: Acciones de GitHub
• Receta CI/CD: Jenkins
• Receta CI/CD: GitLab CI

Cada receta muestra el proceso completo (instalar → autenticar → empaquetar → publicar → implementar → probar), la conexión secreta, una entrada de caché y variaciones para anclar versiones y ejecutar pruebas.

Ver también

• Tu primer proceso : el flujo mínimo de tres comandos.
• Tutorial: empaquetar y publicar una solución : disciplina de versiones, promoción multientorno, reversión.
• Autenticación : los tres flujos y cuándo utilizar cada uno.
• Patrones de scripting : códigos de salida, reintento, filtrado JSON.
• Instalación de UiPath CLI — CI/CD — detalles de preinstalación y almacenamiento en caché.