CI/CD レシピ: Jenkins

UiPath ソリューションの認証、パッキング、パブリッシュ、デプロイ、および Test Manager テストの実行を行うための、完全な宣言型 Jenkinsfile です。

このページでは、CLI のインストール、外部アプリケーションでの認証、UiPath ソリューションのパッケージ化とパブリッシュ、Orchestrator へのデプロイ、および Test Manager スイートの実行を、宣言 的な Jenkinsfile で完全に説明しています。これをリポジトリのルートに配置し、一致する Jenkins 資格情報エントリを作成すると、パイプラインが実行されます。

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

前提条件

Jenkinsfile をコピーする前に、以下を実行します。

1. パイプラインに必要なOR.*スコープを持つ外部アプリケーションを UiPath で作成します。「認証 — フロー 2」を参照してください。
2. シークレットを Jenkins の資格情報に保存します。
   • Jenkins の → 資格情報を System → Global Credentials (無制限) →管理します。
   • ID が UIPATH_CLIENT_ID と UIPATH_CLIENT_SECRETの 2 つの [シークレット テキスト] エントリを追加します。
   • ID が UIPATH_TENANT (テナント名。厳密にはシークレットではありませんが、資格情報が最も移植性の高い場所です) の [プレーン テキスト] または [シークレット テキスト] エントリを追加します。
3. エージェントの要件。このパイプラインは、Node.js 22+ で linux というラベルの付いたエージェントを想定しており、PATH に npm があります。Windows またはコンテナーで実行する場合は、以下の 代替エージェントのオプション を参照してください。
4. テスト ステージが必要な場合は、Test Manager プロジェクトとテスト セットをプロビジョニングします。TEST_SET_KEYと PROJECT_KEY を追加の資格情報として (またはパイプライン パラメーターとして) 追加します。

Jenkinsfile

pipeline {
  agent none

  options {
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: '30'))
    disableConcurrentBuilds()
  }

  environment {
    CLI_VERSION      = '1.0.0'
    SOLUTION_NAME    = 'my-solution'
    SOLUTION_DIR     = 'my-solution'
    OUTPUT_DIR       = 'dist'
    SOLUTION_VERSION = "1.2.0-ci.${env.BUILD_NUMBER}"

    // npm global prefix for a user-local, no-sudo install
    NPM_PREFIX       = "${env.WORKSPACE}/.npm-global"
  }

  stages {

    stage('Build') {
      agent { label 'linux' }
      steps {
        checkout scm
        sh '''#!/usr/bin/env bash
          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

          mkdir -p "$OUTPUT_DIR"
          uip solution pack "$SOLUTION_DIR" "$OUTPUT_DIR" \
            --name "$SOLUTION_NAME" \
            --version "$SOLUTION_VERSION"
        '''

        // Carry the .zip to the Deploy stage, which runs on a fresh agent.
        stash name: 'solution-zip', includes: "${OUTPUT_DIR}/*.zip"

        archiveArtifacts artifacts: "${OUTPUT_DIR}/*.zip", fingerprint: true
      }
    }

    stage('Deploy') {
      agent { label 'linux' }
      steps {
        unstash 'solution-zip'

        withCredentials([
          string(credentialsId: 'UIPATH_CLIENT_ID',     variable: 'UIPATH_CLIENT_ID'),
          string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET'),
          string(credentialsId: 'UIPATH_TENANT',        variable: 'UIPATH_TENANT')
        ]) {
          sh '''#!/usr/bin/env bash
            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 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}-${BUILD_NUMBER}" \
              --package-name "$SOLUTION_NAME" \
              --package-version "$SOLUTION_VERSION" \
              --folder-name MySolution \
              --parent-folder-path Shared
          '''
        }
      }
    }

    stage('Test') {
      when {
        expression { return env.TEST_SET_KEY?.trim() }
      }
      agent { label 'linux' }
      steps {
        withCredentials([
          string(credentialsId: 'UIPATH_CLIENT_ID',     variable: 'UIPATH_CLIENT_ID'),
          string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET'),
          string(credentialsId: 'UIPATH_TENANT',        variable: 'UIPATH_TENANT'),
          string(credentialsId: 'TEST_SET_KEY',         variable: 'TEST_SET_KEY'),
          string(credentialsId: 'PROJECT_KEY',          variable: 'PROJECT_KEY')
        ]) {
          sh '''#!/usr/bin/env bash
            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 login \
              --client-id env.UIPATH_CLIENT_ID \
              --client-secret env.UIPATH_CLIENT_SECRET \
              --tenant "$UIPATH_TENANT"

            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
          '''
        }
      }
    }
  }

  post {
    always {
      // Best-effort cleanup; uip logout only matters on a persistent agent.
      node('linux') {
        sh '''
          if command -v uip >/dev/null; then
            uip logout || true
          fi
        '''
      }
    }
  }
}

チュートリアル

最上位のセットアップ

• 上部にあるagent noneは、パイプラインに既定のエージェントがないことを宣言しています。各ステージは、agent { label 'linux' }で独自のものを選択します。これにより、ビルドを大容量エージェントに配置し、インフラストラクチャがロックダウンされたエージェントに分散している場合は、そのようにデプロイできます。
• options — timestamps() はすべてのコンソール行に [2026-04-24T10:30:12] プレフィックスを追加するため、長時間の実行のデバッグがはるかに簡単になります。disableConcurrentBuilds() 、2 つのデプロイが同じ Orchestrator フォルダーに競合することが防止されます。
• environmentブロック — 他のレシピと同じパターンです: ピンCLI_VERSION、 BUILD_NUMBERからSOLUTION_VERSIONを計算し、 npm のグローバルプレフィックスをワークスペースにルーティングするため、インストールはビルドごとに行われ、sudoは必要ありません。

ビルド ステージ

• checkout scm — Jenkins は、宣言型パイプラインでこれを明示的に必要とします。
• インストール手順 — 他のプラットフォームと同じ if ! command -v uip ガードです。workspace-local npm プレフィックス ($NPM_PREFIX) は、すべてのビルドがクリーンに開始されることを意味します。実行間でキャッシュが行われない。Jenkins エージェントが永続的で、CLI をキャッシュする場合は、ジョブキャッシャープラグインを使用するか、${env.WORKSPACE}ではなくエージェント上のパスに NPM_PREFIX を設定します。
• パックステップ — 明示的なバージョンでストレート uip solution pack 。
• stash name: 'solution-zip' — これはジェンキンス特有の作品です。GitHub Actions 成果物や Azure Pipelines publishとは異なり、 stash はパイプラインの実行にスコープが設定され、ワークスペースを保持することなく、ステージ間で存続します。stash は glob (${OUTPUT_DIR}/*.zip) を使用するため、生成したファイル名 uip solution pack 取得します。.zip を必要とするすべてのステージは、開始時にunstash 'solution-zip'を呼び出します。stash / unstashに関する Jenkins ドキュメントを参照してください。
• archiveArtifacts — .zipのコピーもビルドページに表示され、人間がダウンロードすることができます。fingerprint: true を使用すると、Jenkins は複数のジョブにわたって追跡できます。

デプロイ ステージ

• unstash 'solution-zip'ワークスペースに.zipを復元します。新しいエージェントと組み合わせることで、「ビルドコンテキスト」と「デプロイコンテキスト」が明確に分離されます。
• withCredentials は、3 つの資格情報エントリを、sh ブロックに表示される環境変数にバインドします。クロージャはクレデンシャルセーフ境界です — 値はコンソールログでマスクされ、このブロックの外側のステップにリークされることはありません。Orchestrator と通信するすべての uip 呼び出しに使用します。
• uip login は env.UIPATH_CLIENT_ID / env.UIPATH_CLIENT_SECRET を使用します — env.VAR_NAME プレフィックスは withCredentialsによって設定された変数を読み取ります。「認証 — 環境」を参照してください。VAR_NAMEプレフィックス。シークレットをコマンドラインに直接補間しないでください (--client-secret "$UIPATH_CLIENT_SECRET") — レンダリングされたシェルコマンドに埋め込まれ、一部のログ設定ではコンソール出力に埋め込まれます。
• パブリッシュ + デプロイ — uip solution publishしてからuip solution deploy run。--name "${SOLUTION_NAME}-${BUILD_NUMBER}"、各デプロイのレコードをその Jenkins ビルドまでさかのぼることができますが、--folder-name/--parent-folder-pathは静的であり、deploy runは常に新しいフォルダーに新しいデプロイを作成します。既存のプロンプトは更新されません。すでにデプロイ済みのパッケージに対して繰り返し実行すると、アクティビティは停止し、アップグレード パスを指定します (競合によって名前が変更された 2 つ目のコピーをデプロイする --yesを除く)。このプレフライトチェックにはユーザーセッションが必要なため、このパイプラインで使用するクライアント資格情報ログインでは完全にスキップされます — ここでのグリーンビルドごとに新しいフォルダーが作成されます。代わりに、既存のデプロイを更新するには、 を使用します uip solution deploy upgrade <deployment-key> を使用します ( でキーを検索します uip solution deploy list --folder-path Shared)。

テストステージ

when { expression { return env.TEST_SET_KEY?.trim() } }によるゲート — TEST_SET_KEY資格情報を設定しない (または空のままにする) と、ステージはスキップされます。シェルブロックは、「 方法:CLIからテストを実行する 」 →パターンの検証→待機 する正規の起動です。

1. uip tm testsets run が起動し、ExecutionIdが返されます。
2. 実行が終了ステートに達するまでブロックuip tm wait。waitでは、終了2コードはタイムアウトを意味します(認証の失敗ではなく、ドメイン固有のコードの再利用です)。
3. uip tm report getData.Failedを読み取り、テストが失敗するとシェルは1終了します。

投稿 { always }

ベストエフォートuip logout一時的なエージェントでは、これは不要です。永続エージェントでは、ワークスペースローカルの .uipath/ フォルダーがクリアされるため、同じワークスペース上の後続のジョブで古いセッションが再利用されません。|| true は、uip がインストールされていない (インストール前にビルドが失敗した) 場合、エラーを飲み込みます。

一般的なバリエーション

エージェントのバリエーション

• Windows エージェント — sh を batに置き換え、bash スクリプトを cmd.exe または PowerShell に変換します。env. プレフィックスとすべての uip コマンドは同一です。周囲のシェルのみが変更されます。「 UiPath CLI のインストール — Windows」をご覧ください。
• Dockerエージェント — agent { docker { image 'node:22' } } 、エージェント構成がゼロのビルドごとに新しいノードランタイムを提供します。ルートフルイメージにsudo-freeグローバルnpmをインストールする必要がある場合は、 args '-u root' を追加します。それ以外の場合は、上記のように NPM プレフィックスを $WORKSPACE/.npm-global に設定し、特権ダンスをスキップします。
• Kubernetes プラグイン — node:22 コンテナーでポッド テンプレートを使用し、 /root/.npm-global を PVC としてマウントして、ビルド間で CLI をキャッシュします。

環境間でプロモートする

各環境を独自のステージに変換し、同じ stashを再利用します。

stage('Deploy stage') {
  agent { label 'linux' }
  steps {
    unstash 'solution-zip'
    withCredentials([string(credentialsId: 'UIPATH_STAGE_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'), ...]) {
      sh '...deploy to stage tenant...'
    }
  }
}

stage('Approval') {
  steps {
    input message: 'Deploy to production?', ok: 'Deploy'
  }
}

stage('Deploy prod') {
  agent { label 'linux' }
  steps {
    unstash 'solution-zip'
    withCredentials([string(credentialsId: 'UIPATH_PROD_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'), ...]) {
      sh '...deploy to prod tenant...'
    }
  }
}

input手順では、人間が [デプロイ] をクリックするまでパイプラインを一時停止します。Jenkins の マトリックス承認戦略 を使用して、承認できるユーザーを制限します。「使い方」のより詳細な説明 : ソリューションをパッケージ化してパブリッシュする — 1 つのパッケージを複数のテナントに昇格させます。

ロールバック

パラメーター化されたジョブ ( Jenkins → New Item → Pipeline → このプロジェクトは [パラメーター (文字列)] → "ROLLBACK_VERSION" →パラメーター化 され、ガードされたステージを追加します。deploy run ではなく deploy upgrade を使用します。deploy run、ロールバックするデプロイに触れる代わりに、まったく新しいフォルダーを作成します。

stage('Rollback') {
  when { expression { return params.ROLLBACK_VERSION?.trim() } }
  agent { label 'linux' }
  steps {
    withCredentials([/* UIPATH_* credentials */]) {
      sh '''#!/usr/bin/env bash
        set -euo pipefail
        # …install + login…

        DEPLOYMENT_KEY=$(uip solution deploy list --folder-path Shared \
          --output-filter "Data[?Name=='MySolution'].Key | [0]" --output plain)
        uip solution deploy upgrade "$DEPLOYMENT_KEY" --version "$ROLLBACK_VERSION"
      '''
    }
  }
  environment {
    ROLLBACK_VERSION = "${params.ROLLBACK_VERSION}"
  }
}

[パラメーター を使用したビルド] を使用して、[構築] ページからトリガーします。deploy upgrade 、デプロイの既存の設定は保持されます。すでに設定されているアセット/資格情報の値は、パッケージの既定値にリセットされません。破壊的なロールバック (アンインストール + アーティファクトの削除) については、「 ハウツー: ソリューションをパッケージ化して公開する — ロールバック」を参照してください。

よくある落とし穴

• withCredentials スコーピング。認証情報はクロージャー内でのみ利用可能です。uip login を withCredentials 内で呼び出し、uip solution publish を外部で呼び出した場合、2 番目のコマンドにはセッションがありません。CLI ブロック全体を 1 つの withCredentials内に保持します。
• エージェントを変更する前にstashしてください。あるステージで宣言された stash は、エージェントが切り替わる前にスタッシュ・ステップが完了していた場合にのみ、後のステージで使用できます。Build ステージのシェル ブロックが stashより前に 0 以外から出た場合、後のステージは unstashで失敗します。このレシピのようにstashshブロックの外に置くことで、シェルの結果に関係なく、クリーンなエージェントで動作するようになります。
• 間違ったタイミングで|| true。postのuip logout || trueは、唯一の障害モードが「uipがインストールされなかった」であるため安全です。初期の段階で || true を唐辛子にしないでください—それは本当の失敗を隠します。
• sh ストリクト モードです。sh ブロックのすべての bash スクリプトを #!/usr/bin/env bash と set -euo pipefailで開始します。既定の Jenkins シェルは /bin/shです。これは pipefailをサポートしていません。スクリプトパターン — 厳密なシェルオプション を参照してください。
• Groovyの複数行の文字列。シェル本体にはトリプルシングルクォート文字列 ('''...''') を優先します — $VARを補間しないため、変数は Groovy ではなく bash で展開されます。これにより、一般的なクラスの「変数が空である」というバグが回避されます。パイプラインのコンパイル時にGroovyに入力させたい値については、 ${env.SOME_VAR} 明示的に使用してください。

参照

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