CI/CDレシピ:GitLab CI

このページでは、CLI のインストール、外部アプリケーションでの認証、UiPath ソリューションのパッケージ化とパブリッシュ、複数のテナントにまたがる Orchestrator へのデプロイ (マトリクス経由)、および Test Manager スイートの実行.gitlab-ci.ymlについて説明します。これをリポジトリのルートにドロップし、3 つの CI/CD 変数を設定して実行します。

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

前提条件

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

1. パイプラインに必要なOR.*スコープを持つ外部アプリケーションを UiPath で作成します。「認証 — フロー 2」を参照してください。
2. シークレットを CI/CD 変数として保存します。
   • プロジェクト→設定 → CI/CD →変数
   • UIPATH_CLIENT_IDとUIPATH_CLIENT_SECRETを追加します。両方を [ マスク ] と [保護 ] としてマークします (つまり、保護されたブランチ/タグでのみ公開されます)。
   • UIPATH_TENANT_DEV、UIPATH_TENANT_STAGE、UIPATH_TENANT_PROD をテナント名で追加します (マスクされていないため、テナント名は機密扱いではありません)。
3. テスト ジョブが必要な場合は、Test Manager プロジェクトとテスト セットをプロビジョニングします。TEST_SET_KEY と PROJECT_KEY を標準変数として追加します。

.gitlab-ci.yml

# -----------------------------------------------------------------------------
# Deploy UiPath Solution
# -----------------------------------------------------------------------------
# Auth: External Application, env.VAR_NAME prefix (never the literal value).
# Cache: npm global node_modules, keyed by CLI version.
# Matrix: deploy job fans out across dev / stage / prod tenants.
# -----------------------------------------------------------------------------

image: node:20

stages:
  - build
  - deploy
  - test

variables:
  CLI_VERSION: '1.0.0'
  SOLUTION_NAME: 'my-solution'
  SOLUTION_DIR:  './my-solution'
  OUTPUT_DIR:    './dist'
  SOLUTION_VERSION: '1.2.0-ci.$CI_PIPELINE_IID'

  # Workspace-local npm prefix so installs need no sudo and are cacheable.
  NPM_PREFIX: "$CI_PROJECT_DIR/.npm-global"

# Re-usable install block. GitLab does not have anchors for script:; we use
# YAML anchors on a hidden job and extend from it.
.install-uip: &install-uip |
  set -euo pipefail
  mkdir -p "$NPM_PREFIX"
  npm config set prefix "$NPM_PREFIX"
  export PATH="$NPM_PREFIX/bin:$PATH"

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

cache:
  key: "uip-$CLI_VERSION"
  paths:
    - .npm-global/lib/node_modules
  policy: pull-push

# -----------------------------------------------------------------------------
# Stage: build
# -----------------------------------------------------------------------------

pack:
  stage: build
  script:
    - *install-uip
    - mkdir -p "$OUTPUT_DIR"
    - |
      uip solution pack "$SOLUTION_DIR" "$OUTPUT_DIR" \
        --name "$SOLUTION_NAME" \
        --version "$SOLUTION_VERSION"
  artifacts:
    paths:
      - "$OUTPUT_DIR/*.zip"
    expire_in: 30 days

# -----------------------------------------------------------------------------
# Stage: deploy — matrix across environments
# -----------------------------------------------------------------------------

deploy:
  stage: deploy
  needs:
    - job: pack
      artifacts: true
  parallel:
    matrix:
      - ENVIRONMENT: dev
        TENANT_VAR:  UIPATH_TENANT_DEV
      - ENVIRONMENT: stage
        TENANT_VAR:  UIPATH_TENANT_STAGE
      - ENVIRONMENT: prod
        TENANT_VAR:  UIPATH_TENANT_PROD
  environment:
    name: uipath/$ENVIRONMENT
  rules:
    # Prod only on protected branches — set protection under Settings → Repository.
    - if: '$ENVIRONMENT == "prod" && $CI_COMMIT_REF_PROTECTED != "true"'
      when: never
    - when: on_success
  script:
    - *install-uip
    - |
      # Resolve the per-environment tenant from the matrix variable.
      UIPATH_TENANT="${!TENANT_VAR}"
      if [ -z "$UIPATH_TENANT" ]; then
        echo "Tenant variable $TENANT_VAR is empty; set it in CI/CD settings." >&2
        exit 3
      fi

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

      ARTIFACT=$(find "$OUTPUT_DIR" -maxdepth 1 -name "*.zip" | head -1)
      uip solution publish "$ARTIFACT"

      uip solution deploy run \
        --name "$SOLUTION_NAME-$ENVIRONMENT-$CI_PIPELINE_IID" \
        --package-name "$SOLUTION_NAME" \
        --package-version "$SOLUTION_VERSION" \
        --folder-name MySolution \
        --folder-path Shared

# -----------------------------------------------------------------------------
# Stage: test
# -----------------------------------------------------------------------------

test:
  stage: test
  needs:
    - job: "deploy: [dev, UIPATH_TENANT_DEV]"   # depend on the dev leg of the matrix
      optional: true
  rules:
    - if: '$TEST_SET_KEY == null || $TEST_SET_KEY == ""'
      when: never
    - when: on_success
  script:
    - *install-uip
    - |
      uip login \
        --client-id env.UIPATH_CLIENT_ID \
        --client-secret env.UIPATH_CLIENT_SECRET \
        --tenant "$UIPATH_TENANT_DEV"

      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 "test run did not finish within 30 minutes" >&2; exit 2 ;;
          *) echo "wait failed (exit $code)" >&2; 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 "$FAILED test case(s) failed" >&2
        exit 1
      fi

チュートリアル

最上位のセットアップ

• image: node:20 — すべてのジョブは Node.js 20 の公式イメージで実行されます。CLI にはノード 18+ が必要です。GitLabランナーにすでにNodeがインストールされていて、コンテナが必要ない場合は、これを削除して、代わりに shell エグゼキューターを使用できます。
• variables: — パイプライン全体の値。SOLUTION_VERSION $CI_PIPELINE_IID (プロジェクトスコープの増分パイプライン番号 - グローバルで非単調な $CI_JOB_IDよりもバージョン管理に適しています) を補間します。
• .install-uipアンカー — GitLabではscript:ブロックを直接アンカーすることはできませんが、シェル文字列を含むYAMLノードをアンカーし、- *install-uipでつなぎ合わせることができます。他のレシピと同じインストールガード:ワークスペースローカルプレフィックス、条件付きCLIインストール。ツールは初回使用時に自動的にインストールされるため、アンカーはホストのみを処理します。
• cache: — CLI バージョンのバンプによってキャッシュがクリーンに無効になることを保証するキーuip-$CLI_VERSION。policy: pull-push は、開始時に読み取り、ジョブが正常に終了すると書き込みます。大規模に実行し、すべてのジョブを秒単位で短縮する場合は、 pull-push 実行する専用の「シード・ザ・キャッシュ」ジョブに分割し、他のすべてのジョブで policy: pull のみを使用します。

pack ジョブ

• 共有アンカーを介して CLI をインストールします。
• 明示的なバージョンを使用したuip solution pack — uip solution packを参照してください。
• artifacts:.zipを次の段階に進めます。パスはグロブ($OUTPUT_DIR/*.zip)なので、 uip solution pack 生成したファイル名を拾います。expire_in: 30 days 、GitLabのアーティファクトストレージが無制限に増加するのを防ぎます。より長いトレーサビリティが必要な場合は、バンプしてください。

並列: 行列を使用してジョブをデプロイ

マトリックスは、並列で実行される 3 つのジョブ (deploy: [dev, UIPATH_TENANT_DEV]、deploy: [stage, UIPATH_TENANT_STAGE]、deploy: [prod, UIPATH_TENANT_PROD]) に展開されます。それぞれが異なる $ENVIRONMENT と $TENANT_VARを取得し、bash の間接展開 (${!TENANT_VAR}) を使用して、適切な CI/CD 変数から環境ごとのテナントを読み取ります。

• environment: name: uipath/$ENVIRONMENT — GitLab は [環境] ビューでデプロイを追跡するため、すべてのテナントはロールバック ボタンを使用して環境ごとの履歴を取得します。
• rules: — 最初のルールは、保護されていないブランチからのprodをブロックします。[リポジトリ→保護されたブランチ→設定] (main保護とマークする場所) と組み合わせて使用すると、機能ブランチが誤って運用環境にデプロイされるのを防ぐことができます。UIPATH_CLIENT_*変数も protected とマークして、保護された参照でのみ解決されるようにする必要があります。
• uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET — env.VAR_NAMEプレフィックスは、シェルコマンドラインに表示されないシークレットをCLIに渡すためにサポートされている方法です。GitLabは、 マスクされたとマークされるとログ内の変数をマスクしますが、 env. プレフィックスはとにかく多層防御です。「認証 — 環境」を参照してください。VAR_NAMEプレフィックス。
• デプロイ名 — $SOLUTION_NAME-$ENVIRONMENT-$CI_PIPELINE_IID 、各デプロイを特定のパイプライン実行と環境にトレースできるようにします。

注:

並列行列ジョブでは、片方の脚に障害が発生しても、他の脚は既定で実行され続けます。prod で dev と stage を待つ場合は、代わりにマトリックスを 3 つの連続したジョブに変換します (または、それらの間で needs: を使用します)。

テスト ジョブ

• needs: は、行列レッグを展開した名前 ( "deploy: [dev, UIPATH_TENANT_DEV]") で参照します。この optional: true により、開発レッグが rules: ブロックによってスキップされた場合、依存関係は致命的ではありません。
• rules: TEST_SET_KEY が未設定の場合、他のレシピと同じパターンでジョブをスキップします。
• Launch → wait → verify — 「 How-to: run tests from the CLI」の正規のテストパターン。exit 2 fromuip tm wait はタイムアウトを意味します (認証の失敗ではありません)。

一般的なバリエーション

マニュアルゲートによるシリアルプロモーション

prod で protected-branch ゲートではなく手動クリックを要求する場合は、マトリックスを 3 つのジョブに分割し、prod ジョブに when: manual を追加します。

deploy-dev:
  stage: deploy
  # …as deploy above, fixed to UIPATH_TENANT_DEV…

deploy-stage:
  stage: deploy
  needs: [ pack, deploy-dev ]
  # …as deploy above, fixed to UIPATH_TENANT_STAGE…

deploy-prod:
  stage: deploy
  needs: [ pack, deploy-stage ]
  when: manual                    # requires a reviewer to click "Play"
  allow_failure: false
  environment:
    name: uipath/prod
  # …as deploy above, fixed to UIPATH_TENANT_PROD…

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

ロールバック

パイプライン変数を使用して別のジョブを介して手動でトリガーする:

rollback:
  stage: deploy
  when: manual
  rules:
    - if: '$ROLLBACK_VERSION != null && $ROLLBACK_VERSION != ""'
  script:
    - *install-uip
    - |
      uip login \
        --client-id env.UIPATH_CLIENT_ID \
        --client-secret env.UIPATH_CLIENT_SECRET \
        --tenant "$UIPATH_TENANT_PROD"

      uip solution deploy run \
        --name "$SOLUTION_NAME-rollback" \
        --package-name "$SOLUTION_NAME" \
        --package-version "$ROLLBACK_VERSION" \
        --folder-name MySolution \
        --folder-path Shared

[CI/CD → パイプライン] → [パイプラインを実行] からパイプラインを開始し、[ROLLBACK_VERSION] をターゲット バージョン (例: 1.1.9) に設定します。破壊的なロールバック (アンインストール + 成果物の削除) については、「 方法: ソリューションをパックして発行する — ロールバック」を参照してください。

テストをスキップ

CI/CD 変数 TEST_SET_KEY 未設定のままにします。test ジョブの rules: ブロックでは、このジョブは正常にスキップされます。

よくある落とし穴

• マスク != 保護されています。マスクされた変数はログ内の値を非表示にしますが、すべてのブランチ (有効期間の短い機能ブランチを含む) で引き続き使用できます。protected 変数は protected ref でのみ公開されます。認証シークレットには 両方 が必要です — そうしないと、プッシュされた機能ブランチが prod に対して uip login 実行される可能性があります。
• 間接的な拡張にはbashが必要です。${!TENANT_VAR} bash の機能です。一部の最小画像のデフォルト sh ではサポートされていません。node:20イメージには、既定で bash が含まれています。alpineベースのイメージでは、明示的な環境変数apk add bash または case ステートメントに切り替えます。
• マトリックスのジョブ名にはスペースが含まれています。needs: - job: "deploy: [dev, UIPATH_TENANT_DEV]" — 名前には の : [が含まれているので、YAML で引用符で囲みます。
• キャッシュ パスはワークスペースを基準にしています。キャッシュエントリ .npm-global/lib/node_modules は、ワークスペース内に配置するため NPM_PREFIX="$CI_PROJECT_DIR/.npm-global" 機能します。プレフィックスを外部に移動すると、キャッシュは機能しなくなります。
• set -euo pipefail、すべての複数行スクリプトの先頭に配置する必要があります。これがないと、失敗したパックの後に、古いアーティファクトの「成功した」公開が続く可能性があります。スクリプトパターン — 厳密なシェルオプション を参照してください。

参照

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