CI/CD レシピ: Azure Pipelines

このページでは、CLI のインストール、外部アプリケーションでの認証、UiPath ソリューションのパッケージ化とパブリッシュ、Orchestrator へのデプロイ、デプロイに対する Test Manager スイートの実行をすべてazure-pipelines.yml説明します。パイプラインは自己完結型です。リポジトリのルートにコピーし、2 つのシークレットを配線して実行します。

基本原則 (認証、キャッシュ、ツールのプレインストール、バージョンのピン留め) については、「 方法: CI から Orchestrator にデプロイする」をご覧ください。このページでは、Azure Pipelines 構文に焦点を当てています。

前提条件

以下の YAML をコピーする前に:

1. パイプラインに必要なOR.*スコープを持つ外部アプリケーションを UiPath で作成します。「認証 — フロー 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ピンはバージョン20 Node.js。メジャーにピン留めします。CLI には 18+ が必要です。
• Cache@2 は npm グローバル node_modules ディレクトリをキャッシュします。キャッシュキーには $(CLI_VERSION) が含まれているため、バージョンのバンプはきれいに無効になります。
• Install step は、npm のグローバルプレフィックスを $HOME/.npm-global ( sudo 不要) に切り替え、それを PATH の先頭に追加し、キャッシュが欠落した場合にのみ @uipath/cliをインストールします。ツールコマンド(uip solution …、 uip tm …)を最初に呼び出すと、そのツールが自動インストールされるため、明示的な uip tools install は必要ありません。「 UiPath CLI をインストールする — CI/CD 」および 「スクリプト パターン — バージョンをピン留めする」をご覧ください。
• pack ステップは、明示的な--versionでuip solution packを呼び出します (CI の 1.0.0 デフォルトに依存しないでください)。
• publish: ... $(OUTPUT_DIR)全体を solution-zip という名前のパイプライン成果物としてアップロードし、Deploy ステージで使用できるようにします。ハードコードされたファイル名ではなくディレクトリを公開すると、CLI の命名規則の変更後もレシピが安定します。

ステージ 2 — デプロイ

指定された環境にバインドされた デプロイ ジョブ を使用します。環境は、Azure DevOps でゲートと承認を構成する場所であり、YAML 自体はシンプルです。

• CLI を再インストールします (キャッシュは、同じ実行の 2 番目のステージでヒットします)。
• uip login では、クライアント ID とシークレットの両方に env.VAR_NAME プレフィックスが使用されます。ステップレベルのenv:ブロックは、フラグが解決する実際の環境変数UIPATH_CLIENT_IDに(変数グループから)$(UIPATH_CLIENT_ID)マップします。シークレットをコマンドライン(--client-secret "$(UIPATH_CLIENT_SECRET)")で文字通り渡さないでください—ビルドログとps出力に漏れます。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: ガードはステージをきれいにスキップします。

シェル ブロックは、「 方法: CLI からテストを実行する 」 →フローの検証→待機 する正規の起動です。

1. uip tm testsets run実行を起動してExecutionIdを返します。
2. 実行が終了状態に達するまでブロックuip tm wait(exit 2 はタイムアウトを意味し、認証の失敗 (終了コード スロットのドメイン固有の再利用) ではありません)。
3. uip tm report getは Data.Failed;手順は ##vso[task.logissue type=error] で失敗するため、結果は Azure DevOps UI に明確に表示されます。

一般的なバリエーション

環境間でプロモートする

2 つの変数グループ ( 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

「使い方」のより詳細な説明 : ソリューションをパッケージ化してパブリッシュする — 1 つのパッケージを複数のテナントに昇格させます。

ロールバック

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ステージブロックを削除します(または、ステージ上のcondition:がスキップTEST_SET_KEY、未設定のままにします)。

よくある落とし穴

• env. プレフィックスとリテラルシークレット。常に --client-secret env.UIPATH_CLIENT_SECRETし、 --client-secret "$(UIPATH_CLIENT_SECRET)"することはありません。リテラル形式は、レンダリングされたコマンドラインに値を埋め込みます。認証の警告を参照してください。
• ##vso[task.setvariable]はenv.の解決には必要ありません。ステップ上のenv:変数は変数を直接公開します。
• 複数行の bash では、すべての script: ブロックの先頭に set -euo pipefailが必要です。Choice テーブルがなければ、 pack 失敗しても後のステップは実行され続ける可能性があります。スクリプトパターン — 厳密なシェルオプション を参照してください。
• キャッシュ ヒットは保証されません。インストール コマンドは常に if ! command -v uip でラップし、キャッシュがコールドになったときにパイプラインが自己修復されるようにします。

参照

• 方法: CI から Orchestrator にデプロイ する — プラットフォームに依存しないガイダンス。
• 方法: ソリューションをパッケージ化してパブリッシュする — バージョン管理とロールバック
• 方法: CLI からテストを実行する — 起動→待機→検証パターンの詳細。
• CI/CD レシピ: GitHub Actions、 Jenkins、 GitLab CI — 他のプラットフォームの同じパイプライン。