操作方法：从 CI 部署到 Orchestrator

本页涵盖部署 UiPath 解决方案的每个 CI 管道的需求，无论您在 Azure DevOps、GitHub Actions、Jenkins 还是 GitLab 上运行：身份验证、缓存、工具预安装和版本固定。公式页面中包含特定于平台的语法 — 此页面为您提供了活动部件，因此您可以自信地阅读其中任何部分。

良好的 CI 管道的形状

交付解决方案的生产管道始终具有相同的五个阶段：

1. 设置 Node.js （18 版或更高版本）。
2. 安装@uipath/cli已固定版本。
3. 预安装您将使用的工具（因此第一个uip调用不比其余调用慢）。
4. 对外部应用程序进行身份验证，方法是使用密码前缀env. 。
5. 打包、发布、部署— 以及测试（可选）。

第 4 阶段是平台之间变化最大的阶段，因为密码语法是特定于平台的。第 1-3 阶段和第 5 阶段在所有位置几乎相同。

身份验证：外部应用程序 + 环境变量前缀

在无头环境中，您使用外部应用程序（客户端凭据）进行身份验证。有关如何在 UiPath 门户中创建身份验证，请参见身份验证 — 流程 2 。

将凭据存储在平台的密码存储区中（永远不会存储在来源控件中，也不会存储在普通的 env var 文件中）。将它们传递给带有特殊env.前缀的uip login ：

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

env.VAR_NAME前缀告知uip在运行时从VAR_NAME环境变量中读取值。这使机密信息不会出现在 Shell 历史记录和流程列表中。与--client-secret "$UIPATH_CLIENT_SECRET"不同，后者在命令行中展开，并可能通过ps泄漏。

警告：

不要依赖隐式环境变量读取。如果没有该标志，则单独设置UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET无法对您进行身份验证 — 该功能在 CLI 1.0 之前已被删除。始终传递标志；当您希望从环境中解析值时，请使用env.VAR_NAME 。

在您的管道中，使用您引用的确切变量名称将密码注入到步骤的环境中：

平台	YAML/Groowy 中的密码语法	传递到步骤的形状
GitHub 操作	${{ secrets.UIPATH_CLIENT_ID }} 在 env:	UIPATH_CLIENT_ID: <value>
Azure DevOps	$(UIPATH_CLIENT_ID) 位于的变量组中 env:	UIPATH_CLIENT_ID: $(UIPATH_CLIENT_ID)
Jenkins	credentialsId: 'UIPATH_CLIENT_ID' 内部 withCredentials	导出为 $UIPATH_CLIENT_ID
亚腾 CI	UIPATH_CLIENT_ID CI/CD 变量，标记为“受保护+已掩码”	$UIPATH_CLIENT_ID 在 script

在每种情况下， uip login命令本身看起来都相同 — --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET 。仅环境变量在步骤中的到达方式会发生变化。

会话存储

uip login将会话保留在.uipath/文件夹中。在大多数 CI 运行器上，工作目录已经是无状态的，因此会话将在作业完成后结束，这是预期的行为。如果您的运行器是持久性的，请在作业结束时删除与uip logout会话，或将--file设置为作业本地路径。请参阅会话和凭据。

多个组织位于一个管道中

一个会话一次只能容纳一个组织和一个租户。要以同一管道中的不同 UiPath 组织为目标（例如，将解决方案从构建组织提升为客户组织），请使用不同的外部应用程序在两个块之间重新运行uip login 。每次登录都会覆盖上一个会话。

为每个组织创建一个外部应用程序（每个外部应用程序都有自己的OR.*作用域）。以不同名称将客户端 ID 和密码存储在管道的密码存储区中：

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

单个组织内的不同租户使用相同模式 — 不同之处在于租户不需要再次登录。在任何uip or …调用上传递--tenant <name>以覆盖单个命令的会话租户，而无需重新进行身份验证。

备注：

这是一个序列模式。每个uip login都会覆盖存储的会话，因此在任何时候都只能访问一个组织。如果您需要同时对两个组织运行命令（例如，并行矩阵作业），请为每个作业提供自己的运行程序或--file / HOME作用域 — 请参阅会话和凭据。

预安装工具，以保持构建时间的确定

CLI 附带任何预装工具。首次从已卸载的工具运行动词时， uip会从 npm 自动安装该工具，这在笔记本电脑上应该没有问题，但在无状态 CI 运行程序上，会比第一条命令增加 5–10 秒的延迟。

安装预先使用的工具，作为单独的步骤：

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

在运行 Test Manager 时添加@uipath/test-manager-tool ，在部署智能体时添加@uipath/agent-tool ，在解决方案之外管理资产/队列/存储桶时添加@uipath/resource-tool 。有关完整列表，请参阅工具参考。

如果已安装工具，则自动安装不会执行任何操作，因此预安装步骤是您唯一需要更改的行为 — 管道中的其他任何内容都不必了解相关信息。

备注：

CI=true不会禁用自动安装。没有 env-var 开关；预安装是避免这种情况的唯一方法。请参阅安装 UiPath CLI — 控制工具自动安装。

缓存 npm 全局目录

如果为每个作业重新安装@uipath/cli ， CI 运行程序会浪费 20–40 秒的下载和解压缩时间。缓存 npm 全局node_modules目录会将其转化为缓存点击 — 通常不到一秒。

要缓存的目录是由npm root -g报告的目录（在 Linux/macOS 上通常为~/.npm-global/lib/node_modules ，在 Windows 上为%APPDATA%\npm\node_modules ）。在您固定的 CLI 版本上键入缓存，因此版本提升会使缓存完全失效：

平台	缓存机制
GitHub 操作	actions/cache包含path: ~/.npm-global/lib/node_modules和key: uip-${{ version }}-${{ runner.os }}
Azure DevOps	Cache@2 键入版本变量
Jenkins	作业缓存器插件或手动管理的工作区文件夹
亚腾 CI	包含cache:顶级key: uip-$CLI_VERSION块

当缓存击中时，您可以跳过npm install -g @uipath/cli和uip tools install — 可执行文件uip及其工具已在PATH中。一个小型的 bash Guard 可以干净地完成此操作：

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

有关每个平台的具体 YAML/Gro起来，请参阅秘方页面。

固定版本以提高可重复性

可重现的管道固定所有内容。四个重要版本：

• Node.js — 固定专业（GitHub Actions 的20.x上的setup-node ，Azure DevOps 上的versionSpec: '20.x' ）。
• @uipath/cli — 精确固定 ( @1.0.0 )，而非范围。
• 工具— 可选。默认情况下，它们遵循 CLI 的 MAJOR.MINOR 行；仅在需要补丁级严格的重现性时固定 ( @uipath/solution-tool@1.0.2 )。
• 您自己的解决方案版本— 将--version显式传递给uip solution pack 。永远不要依赖 CI 中的默认1.0.0 。

# 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"

.zip路径是确定性 ( ./dist/my-solution.${SOLUTION_VERSION}.zip )，因此下游步骤无需解析uip solution pack JSON 输出即可构建它。

请参阅“脚本模式 — 在 CI 中固定版本”，深入了解工具固定规则。

最小部署块

每个平台都可归结为：

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使脚本快速失败： -e在任何非零退出时中止， -u捕获未定义的变量， -o pipefail通过管道传播故障。这是本文档中的每个秘钥都使用的模式。请参阅脚本编写模式—严格 shell 选项。

可选：部署后运行测试

如果解决方案包含测试集，请启动 → 等待 → 验证，然后再将管道标记为绿色。这三步模式很重要： uip tm testsets run在运行加入队列后立即退出0 ，而非在测试通过时退出 — 因此您需要uip tm wait进行阻止，并需要uip tm report get来读取结果。

请参阅操作方法：从 CLI 运行测试，了解包含错误处理的完整模式。

处理管道中段的重新身份验证

访问令牌可能会在长时间运行的管道中过期。“脚本模式”页面具有规范的重试模式：根据退出代码2 ( AuthenticationError ) 进行分支，重新运行uip login ，重试一次，否则失败。在大多数 CI 管道中，这是没有必要的（作业足够短，初始登录的令牌将持续整个运行过程），但长测试套件或多租户提升循环可能会从中受益。

平台秘钥

对于使用平台原生语法表示的可复制粘贴的完整管道：

• CI/CD 秘钥：Azure DevOps
• CI/CD 秘钥：GitHub Actions
• CI/CD 模式：Jenkins
• CI/CD 秘钥：GitLab CI

每个秘方都显示了完整的管道（安装 → 身份验证 → 打包 → 发布 → 部署 → 测试）、机密信息连接、缓存条目以及固定版本和运行测试的变体。

另请参阅

• 您的第一个管道— 最小的三命令流。
• 操作方法：打包并发布解决方案— 版本控制规则、多环境升级、回滚。
• 身份验证— 三个流程以及何时使用每个流程。
• 脚本编写模式— 退出代码、重试、JSON 筛选。
• 安装 UiPath CLI — CI/CD — 预安装和缓存详细信息。