CI/CD 秘方：Azure 管道

此页面为您提供完整的azure-pipelines.yml ，用于安装 CLI，使用外部应用程序进行身份验证，打包并发布 UiPath 解决方案，将其部署到 Orchestrator，以及针对部署运行 Test Manager 套件。管道是独立的：将其复制到存储库的根目录，连接两个密码，然后运行。

有关基本原则（身份验证、缓存、工具预安装、版本固定），请参阅操作方法：从 CI 部署到 Orchestrator 。本页重点介绍 Azure 管道语法。

先决条件

在复制以下 YAML 之前：

1. 在 UiPath 中使用管道所需的OR.*作用域创建外部应用程序。请参阅身份验证 — 流程2 。
2. 将密码存储在 Azure DevOps变量组中：
   • “项目设置”→“管道”→ “库” →“新变量组”（例如uipath-prod ）。
   • 添加UIPATH_CLIENT_ID和UIPATH_CLIENT_SECRET — 将两者标记为机密信息（挂锁图标）。
   • 添加UIPATH_TENANT （非密码）。
3. 将变量组链接到管道（请参阅下面的variables块）。
4. 配置Test Manager项目和测试集（如果您需要测试阶段）。您将需要TEST_SET_KEY （格式PROJECT:42 ）和PROJECT_KEY 。请参阅操作方法：从 CLI 运行测试。

Azure Pipelines.yml

trigger:
  branches:
    include: [ main ]

pr:
  branches:
    include: [ main ]

variables:
- group: uipath-prod           # contains UIPATH_CLIENT_ID, UIPATH_CLIENT_SECRET
- name:  CLI_VERSION
  value: '1.0.0'
- name:  NODE_VERSION
  value: '20.x'
- name:  SOLUTION_NAME
  value: 'my-solution'
- name:  SOLUTION_DIR
  value: '$(Build.SourcesDirectory)/my-solution'
- name:  OUTPUT_DIR
  value: '$(Build.ArtifactStagingDirectory)'
- name:  SOLUTION_VERSION
  value: '1.2.0-ci.$(Build.BuildId)'

# Path where npm places globally-installed packages. Used to cache the CLI + tools.
- name:  NPM_GLOBAL_CACHE
  value: '$(HOME)/.npm-global/lib/node_modules'

stages:

- stage: Build
  displayName: 'Pack the Solution'
  jobs:
  - job: pack
    pool:
      vmImage: 'ubuntu-latest'
    steps:

    - task: NodeTool@0
      displayName: 'Use Node.js $(NODE_VERSION)'
      inputs:
        versionSpec: $(NODE_VERSION)

    - task: Cache@2
      displayName: 'Cache npm global (@uipath/cli)'
      inputs:
        key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
        path: $(NPM_GLOBAL_CACHE)

    - script: |
        set -euo pipefail
        mkdir -p "$HOME/.npm-global"
        npm config set prefix "$HOME/.npm-global"
        export PATH="$HOME/.npm-global/bin:$PATH"
        echo "##vso[task.prependpath]$HOME/.npm-global/bin"

        if ! command -v uip >/dev/null; then
          npm install -g "@uipath/cli@$(CLI_VERSION)"
        fi

        uip --version
      displayName: 'Install UiPath CLI'

    - script: |
        set -euo pipefail
        uip solution pack "$(SOLUTION_DIR)" "$(OUTPUT_DIR)" \
          --name "$(SOLUTION_NAME)" \
          --version "$(SOLUTION_VERSION)"
      displayName: 'Pack Solution'

    - publish: '$(OUTPUT_DIR)'
      artifact: solution-zip
      displayName: 'Publish artifact'

- stage: Deploy
  displayName: 'Publish to feed and deploy to Orchestrator'
  dependsOn: Build
  jobs:
  - deployment: deploy
    environment: 'uipath-prod'      # Azure DevOps environment — gates / approvals live here
    pool:
      vmImage: 'ubuntu-latest'
    strategy:
      runOnce:
        deploy:
          steps:

          - task: NodeTool@0
            displayName: 'Use Node.js $(NODE_VERSION)'
            inputs:
              versionSpec: $(NODE_VERSION)

          - task: Cache@2
            displayName: 'Cache npm global (@uipath/cli)'
            inputs:
              key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
              path: $(NPM_GLOBAL_CACHE)

          - script: |
              set -euo pipefail
              mkdir -p "$HOME/.npm-global"
              npm config set prefix "$HOME/.npm-global"
              export PATH="$HOME/.npm-global/bin:$PATH"
              echo "##vso[task.prependpath]$HOME/.npm-global/bin"

              if ! command -v uip >/dev/null; then
                npm install -g "@uipath/cli@$(CLI_VERSION)"
              fi
            displayName: 'Install UiPath CLI'

          - script: |
              set -euo pipefail
              uip login \
                --client-id env.UIPATH_CLIENT_ID \
                --client-secret env.UIPATH_CLIENT_SECRET \
                --tenant "$UIPATH_TENANT"
            displayName: 'Authenticate'
            env:
              UIPATH_CLIENT_ID:     $(UIPATH_CLIENT_ID)
              UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)
              UIPATH_TENANT:        $(UIPATH_TENANT)

          - download: current
            artifact: solution-zip

          - script: |
              set -euo pipefail
              ARTIFACT=$(find "$(Pipeline.Workspace)/solution-zip" -maxdepth 1 -name "*.zip" | head -1)
              uip solution publish "$ARTIFACT"
            displayName: 'Publish to tenant feed'

          - script: |
              set -euo pipefail
              uip solution deploy run \
                --name "$(SOLUTION_NAME)-$(Build.BuildId)" \
                --package-name "$(SOLUTION_NAME)" \
                --package-version "$(SOLUTION_VERSION)" \
                --folder-name MySolution \
                --folder-path Shared
            displayName: 'Deploy to Orchestrator'

- stage: Test
  displayName: 'Run Test Manager suite'
  dependsOn: Deploy
  condition: and(succeeded(), ne(variables['TEST_SET_KEY'], ''))
  jobs:
  - job: test
    pool:
      vmImage: 'ubuntu-latest'
    steps:

    - task: NodeTool@0
      displayName: 'Use Node.js $(NODE_VERSION)'
      inputs:
        versionSpec: $(NODE_VERSION)

    - task: Cache@2
      displayName: 'Cache npm global (@uipath/cli)'
      inputs:
        key:  'uip | "$(Agent.OS)" | $(CLI_VERSION)'
        path: $(NPM_GLOBAL_CACHE)

    - script: |
        set -euo pipefail
        export PATH="$HOME/.npm-global/bin:$PATH"
        echo "##vso[task.prependpath]$HOME/.npm-global/bin"
        if ! command -v uip >/dev/null; then
          npm install -g "@uipath/cli@$(CLI_VERSION)"
        fi

        uip login \
          --client-id env.UIPATH_CLIENT_ID \
          --client-secret env.UIPATH_CLIENT_SECRET \
          --tenant "$UIPATH_TENANT"
      displayName: 'Install + authenticate'
      env:
        UIPATH_CLIENT_ID:     $(UIPATH_CLIENT_ID)
        UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)
        UIPATH_TENANT:        $(UIPATH_TENANT)

    - script: |
        set -euo pipefail

        EXECUTION_ID=$(uip tm testsets run \
          --test-set-key "$TEST_SET_KEY" \
          --output-filter "Data.ExecutionId" \
          --output plain)

        echo "started execution $EXECUTION_ID"

        if ! uip tm wait \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY" \
          --timeout 1800; then
          code=$?
          case "$code" in
            2) echo "##vso[task.logissue type=error]test run did not finish within 30 minutes"; exit 2 ;;
            *) echo "##vso[task.logissue type=error]wait failed (exit $code)"; exit "$code" ;;
          esac
        fi

        uip tm report get \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY"

        FAILED=$(uip tm report get \
          --execution-id "$EXECUTION_ID" \
          --project-key "$PROJECT_KEY" \
          --output-filter "Data.Failed" \
          --output plain)

        if [ "$FAILED" -gt 0 ]; then
          echo "##vso[task.logissue type=error]$FAILED test case(s) failed"
          exit 1
        fi
      displayName: 'Launch, wait, verify'
      env:
        TEST_SET_KEY: $(TEST_SET_KEY)
        PROJECT_KEY:  $(PROJECT_KEY)

演练

阶段 1 — 构建

• NodeTool@0将 Node.js 固定到版本 20。固定到专业； CLI 需要 18+。
• Cache@2缓存 npm 全局node_modules目录。缓存键包含$(CLI_VERSION) ，因此版本提升会完全失效。
• “安装”步骤会将 npm 的全局前缀切换为$HOME/.npm-global （无需sudo ），将其添加到 PATH 路径中，并（仅在缓存未到达的情况下）安装@uipath/cli 。首次调用工具命令（ uip solution … 、 uip tm … ）时，系统会自动安装该工具，因此无需明确的uip tools install 。请参阅安装 UiPath CLI — CI/CD和脚本编写模式 — 固定版本。
• 打包步骤使用显式--version调用uip solution pack （从不依赖 CI 中的1.0.0默认值）。
• publish: ...将整个$(OUTPUT_DIR)作为名为solution-zip管道工件上传，以便部署阶段可以使用它。发布目录而不是发布硬编码文件名，可以在 CLI 命名约定发生更改时使方法保持稳定。

阶段 2 — 部署

使用绑定到命名环境的部署作业。环境是您在 Azure DevOps 中配置网关和审批的位置 — YAML 本身很简单。

• 重新安装 CLI （应在同一运行的第二阶段点击缓存）。
• uip login使用env.VAR_NAME前缀表示客户端 ID 和密码。步骤级别的env:块将$(UIPATH_CLIENT_ID) （来自变量组）映射到标志解析的实际环境变量UIPATH_CLIENT_ID 。不要在命令行 ( --client-secret "$(UIPATH_CLIENT_SECRET)" ) 中按字面意思传递密码，这会将密码泄漏到构建日志和ps输出中。env.前缀功能记录在身份验证 — env.VAR_NAME 前缀中。
• download: current将solution-zip工件从阶段 1 拉取到$(Pipeline.Workspace)/solution-zip 。
• uip solution publish将.zip上传到租户订阅源。
• uip solution deploy run将创建部署。--name使用$(Build.BuildId) ，因此每次运行都是可识别的，并且重新部署不会破坏彼此的部署记录。

第 3 阶段 — 测试

仅当在变量组级别设置了TEST_SET_KEY时才运行 — 如果您未配置测试套件， condition:防护机制会完全跳过该阶段。

shell 块是“操作方法：从 CLI 运行测试” 中 启动 → 等待 → 验证的 规范流程：

1. uip tm testsets run启动运行并返回ExecutionId 。
2. uip tm wait将阻止，直到执行到达终止状态（“退出2表示超时，而不是身份验证失败，即退出代码槽的特定于域的重用）。
3. uip tm report get为Data.Failed ；步骤失败，代码为##vso[task.logissue type=error] ，因此结果可以在 Azure DevOps 用户界面中清晰显示。

常见变体

跨环境提升

链接两个变量组（ uipath-stage和uipath-prod ），并将每个变量组变成单独的deployment:作业。使用特定于环境的步骤/审批来决定 Prod 何时运行：

- stage: DeployStage
  dependsOn: Build
  jobs:
  - deployment: deploy-stage
    variables: [ { group: uipath-stage } ]
    environment: 'uipath-stage'
    # …same steps as above, but with stage's tenant

- stage: DeployProd
  dependsOn: DeployStage
  jobs:
  - deployment: deploy-prod
    variables: [ { group: uipath-prod } ]
    environment: 'uipath-prod'    # attach a manual approval gate here
    # …same steps as above

《操作方法：打包并发布解决方案 — 跨租户推广一个包》中更深入的介绍。

回滚

Azure DevOps 不会自动回滚；添加会重新部署先前版本的手动阶段：

- stage: Rollback
  dependsOn: []                   # run on demand, not from Deploy
  jobs:
  - job: rollback
    pool: { vmImage: 'ubuntu-latest' }
    steps:
    # …install + auth…
    - script: |
        uip solution deploy run \
          --name "$(SOLUTION_NAME)-rollback" \
          --package-name "$(SOLUTION_NAME)" \
          --package-version "$(ROLLBACK_VERSION)" \
          --folder-name MySolution \
          --folder-path Shared
      displayName: 'Re-deploy previous version'

在队列时传递ROLLBACK_VERSION 。有关破坏性回滚（卸载并删除工件），请参阅操作方法：打包并发布解决方案 — 回滚。

正在跳过测试

要不通过测试阶段运行，请删除Test阶段块（或取消设置TEST_SET_KEY — 阶段上的condition:会跳过它）。

常见错误

• env.前缀与文本密码。始终为--client-secret env.UIPATH_CLIENT_SECRET ，从不--client-secret "$(UIPATH_CLIENT_SECRET)" 。常量形式将值嵌入到呈现的命令行中。请参阅身份验证警告。
• ##vso[task.setvariable]解决方案不需要env. — 步骤上的env:会直接公开变量。
• 多行 bash set -euo pipefail在每个script:块的顶部使用 。如果没有它， pack可能会在后续步骤继续运行时失败。请参阅脚本编写模式—严格 shell 选项。
• 无法保证缓存点击。始终将安装命令包含在if ! command -v uip中，以便管道在缓存温度较低时进行自我修复。

另请参阅

• 操作方法：从 CI 部署到 Orchestrator — 与平台无关的指南。
• 操作方法：打包并发布解决方案— 版本控制和回滚。
• 操作方法：从 CLI 运行测试— 启动 → 等待 → 深入验证模式。
• CI/CD 秘钥：GitHub Actions 、 Jenkins 、 GitLab CI — 其他平台中的相同管道。