uipath-solution

UiPath Solution — uip solution のライフサイクル

uip solution CLI を使って、UiPath Solution パッケージ（.uipx）の作成、パック、公開、デプロイ、管理を行います。Solution は複数のオートメーションプロジェクト（プロセス、テスト、エージェントプロジェクト、API ワークフロー）をまとめた、単一のデプロイ可能な単位です。ライブラリはその対象ではありません。ライブラリは個別に公開し、Library リソースとして宣言する場合もあります（Develop a Solution § Step 2）。

CLI を使用してください。Solution の操作で独自の REST 実装を作成しないでください。 HTTP 呼び出しを独自に実装すると、X-UIPATH-OrganizationUnitId フォルダーヘッダー、OData フィルターの形式、ページネーションのエンベロープ、pipelinesInstall のデプロイセマンティクス、再試行の動作、Result/Code/Data の出力契約への対応が漏れてしまいます。CLI が信頼できる情報源です。

プラットフォームのサポート。 Solutions は Automation Cloud とセルフホスト型 Automation Suite（2.2510.0 以降）で実行できます。Standalone Orchestrator では実行できません。利用可能なプロジェクトタイプは AS のバージョンによって異なります（Maestro はセルフホスト型で 2.2510.2 以降のみ）。互換性マトリックスとバージョン別プロジェクトタイプの表 → Solution Overview — Platform availability。

このスキルを使用する場合

• ユーザーが .uipx Solution を持っており、パック／公開／デプロイ／有効化／アップロードしたい場合

• ユーザーが新しい Solution を作成（uip solution init）したい場合、プロジェクトの追加や削除、または Solution リソースの更新をしたい場合

• ユーザーが Studio Web にすでにある Solution を操作したい場合、または別の組織やテナントに移動したい場合 — まず uip solution download を実行します（既存の Solution から開始する）

• ユーザーが UiPath Solution をビルド、公開、デプロイする CI/CD パイプラインのセットアップを依頼した場合

• ユーザーがデプロイ構成、環境への昇格、またはデプロイ済み Solution の有効化について言及した場合

• スキルまたはメインエージェントが .uipx ファイルを検出し、ユーザーをここに誘導した場合

次の場合はこのスキルを使用しないでください：

• タスクが PDD → SDD のアーキテクチャ／設計（sdd.md / pdd.md）の場合 — uipath-planner を読み込みます。
• デプロイ可能なものが単一の非 Solution パッケージ（例：単発の RPA ライブラリやコード化されたアプリ）の場合 — これらには uip rpa publish／uip codedapp publish を使用し、uipath-platform または該当する専門スキルに振り分けます。
• タスクが Solution 以外の Orchestrator 操作（フォルダー、ジョブ、アセット、キュー、IS 接続）の場合 — uipath-platform を読み込みます。

CLI サーフェスの確認

セッションで最初の uip solution … コマンドを実行する前に、solution サーフェスを確認して、名称変更前後の CLI を判別します：

uip solution init --help --output json

• 結果が Success → 名称変更後の CLI（デフォルト）です。参照資料に記載されているコマンドとフラグを使用します。

• unknown command／ゼロ以外の終了コード → 名称変更前の CLI です。各呼び出しの前に、以下の表に従って変換します。後で unknown command エラーが発生した場合は、再度確認します。

• command not found／uip: not found／'uip' is not recognized → CLI がインストールされていません。公式インストーラーを実行するようユーザーに伝えます（macOS/Linux では curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash、Windows PowerShell では irm https://download.uipath.com/uipath-cli/install.ps1 | iex）。続いて uip login を実行し、それらが成功するまで作業を中断します。

名称変更後（デフォルト）	名称変更前の同等コマンド
uip solution init <NAME>	uip solution new <NAME>
uip solution deploy run --parent-folder-path <PATH>	uip solution deploy run --folder-path <PATH>
uip solution deploy run --parent-folder-key <KEY>	uip solution deploy run --folder-key <KEY>
uip solution projects <VERB>	uip solution project <VERB>（名称変更後も単数形は動作しますが、非表示で非推奨です）
uip solution resources <VERB>	uip solution resource <VERB>
uip solution projects import <PATH>	uip solution project import --source <PATH>

その他の solution サブコマンド（pack、publish、deploy activate/status/uninstall、upload、resources …、projects add/remove/list）は、どちらのサーフェスでも変更ありません。

重要なルール

1. セッションで最初の uip solution コマンドを実行する前に、CLI のインターフェースを確認します。 uip solution init --help --output json を実行します。Success はリネーム後の CLI（デフォルト）を示し、unknown command はリネーム前の CLI を示します。その場合は、上記のフォールバック表に従って翻訳してください。以降に unknown command エラーが発生した場合も、再度確認してください。
2. 出力を解析する uip solution コマンドでは、必ず --output json を使用してください。 JSON はコンパクトで安定しており、非対話型実行でのデフォルトです。
3. ソリューションの操作には CLI を使用し、独自の REST を実装しないでください。 手動で作成した HTTP 呼び出しでは、X-UIPATH-OrganizationUnitId ヘッダー、OData フィルター形式、ページネーションのエンベロープ、pipelinesInstall のデプロイセマンティクスが欠落します。そのタスクに対応する uip solution コマンドがないことを確認した場合に限り、REST を使用してください。
4. resources/solution_folder/ を手動で編集しないでください。 このフォルダーは uip solution projects add / import によって自動生成され、projects remove によって自動的にクリーンアップされます。手動編集すると .uipx との同期が崩れ、気づきにくい失敗の原因になります。scenarios/manual-edits.md を参照してください。
5. .uipx と resources/solution_folder/ のプロジェクトセットは、常に一致している必要があります。 両者の差分を確認することが、状態の破損を検出する最も手早い方法です。一致しない場合は、uip solution projects add/remove で修正してください。どちらかを直接編集してはいけません。
6. pack または upload の前に、uip solution resources refresh を実行してください。 バンドルされたアーティファクトファイルと userProfile/<userId>/debug_overwrites.json は、現在のクラウド状態を反映している必要があります。更新を省略すると、古いバインディングがデプロイされます。
7. ソリューション内で作成した AppV2 コード化アプリは、.uipx に登録されます。 uip codedapp init はソリューション側のスキャフォールディングのエントリーポイントです。.uipx ソリューション内で実行してください。project.uiproj（ProjectType: "AppV2"）と webAppManifest.json を書き込み、ソースを source/dist/ の下に配置し、自動的に Type: "AppV2" として登録して resources/solution_folder/app/{Coded,CodedAction}/ を生成します。既存の AppV2 フォルダーにも uip solution projects add / uip solution projects import を使用できます。どちらも webAppManifest.config.isActionApp を読み取って Coded / CodedAction の subType を選択します（マニフェストのない旧式のフォルダーでは、デフォルトで Coded になります）。uip solution pack がこれらをバンドルし、uip solution deploy run がプロビジョニングします。スタンドアロンのコード化アプリはライフサイクルが異なります。uip codedapp init ではなく npx create-vite@latest でスキャフォールディングし、プロジェクトルートにフラットな dist/ を置いて、uip codedapp pack → uip codedapp publish → uip codedapp deploy でデプロイしてください。/uipath:uipath-coded-apps を参照してください。
8. CLI で変更を行うたびに、アーティファクトを検証してください。 project.json、.uipx、または uip solution deploy status の出力を確認してください。終了コードは信頼できません。検証は追加の手順であり、要求された読み取り専用の一覧表示コマンドに代わるものではありません。ユーザーが登録済みプロジェクト、ソリューションリソース、パッケージ、デプロイ、またはステータスの表示や一覧表示を求めた場合は、対応する uip solution ... list/status --output json コマンドを実行してから、二次的な整合性確認としてのみファイルを調べてください。
9. Draft 状態のデプロイは、保留中ではなく失敗したデプロイです。 検証によってリソースが拒否され、インストールが完了していません。状態が自動で進むことはなく、有効化もできません。理由を確認してください。Validation: / Conflicts: は、各デプロイがその実行を待つため、すべてのフィードで失敗の Instructions に表示されます。deploy config set / link で修正し、同じ --name と --package-version を指定して deploy run --config-file <file> を再実行してください。ドラフトが存在する間は、そのデプロイが占有されます。その方法でドラフトを完了するか、破棄する（deploy upgrade <draft-key> --discard-draft、または Orchestrator でドラフトを削除する）まで、他のバージョンは拒否されます。状態を確認するには、同じフィードフラグを指定して deploy list を実行してください。フィードフラグを指定しない場合、テナントスコープとなり、Personal Workspace やフォルダーフィードの行は表示されません。Draft で停止するデプロイ を参照してください。
10. インストール済みリソースをリンクに置き換えるには、明示的な同意が必要です。 deploy run の設定ファイル（deploy config link）または deploy upgrade の新バージョンで、デプロイがすでにインストールしたリソースをリンクすると、サーバーはインストール済みのコピーとそのデータを削除します。新しいサーバーでは事前に確認が求められ、さらに新しい CLI ビルドでは、Deploying '<name>' will permanently delete … installed resource(s) replaced by links: <kind> '<name>', …（deploy upgrade の場合は Upgrading …、ErrorCode: invalid_argument、対象リソースは Data.PermanentDeletionResources にも記載）で停止します。何もインストールされず、試行は保留中のドラフトとして保持されます。これは修正すべき設定エラーではありません。ユーザーがそのコピーとデータの削除を望んでいる場合にのみ確認し、同じコマンドを --acknowledge-permanent-deletion 付きで再実行してください。deploy upgrade では、確認対象のリンク自体が破棄されるため、--discard-draft を併用してはいけません。コピーを保持するには、deploy config unlink <file> <resource> を実行してから再実行する（deploy run）、または deploy upgrade <draft-key> --discard-draft を実行してください（deploy upgrade）。--yes はこの同意の代わりにはなりません。インストール済みリソースをリンクに置き換える を参照してください。
11. 自分の判断で deploy uninstall に --force を指定してはいけません。 これは forceUninstall: true を送信し、未完了のジョブを放棄するとともに、リンクに置き換えられたインストール済みリソースとそのデータを完全に削除します（--yes の代わりにもなります）。アンインストールが Message「…this deployment has uncompleted jobs; --force uninstalls anyway」または「…permanently deletes these resources and their data: '', …」（Data.JobsNotInFinalState、Data.PermanentDeletionResources、Retry: RetryWillNotFix）で失敗した場合は、原因をユーザーに提示し、ユーザーが明示的に同意した場合にのみ --force を追加してください。「…errors that --force cannot get past」（Retry: RetryLater）を回避するために追加してはいけません。Orchestrator で解決してから、--force なしで再実行してください。アンインストールが拒否された場合 を参照してください。
12. 複数の環境へのプロモーションでは、uip login tenant set <tenant> でテナントを切り替え、環境ごとのデプロイ設定を --config-file <path> で指定してください。 同じパック済み .uipx を dev/staging/prod にデプロイできます。環境の違いは、別のパッケージではなく、対象テナントと設定ファイル（deploy config get で生成し、config set / config link で編集）によって決まります。-c <CONFIG_KEY> フラグはありません。

ワークフロー

UiPath ソリューションの一般的なライフサイクルは次のとおりです。

1. init / project add  → Create solution, register projects (.uipx + resources/solution_folder/)
2. resources refresh   → Sync bundled artefacts and debug overwrites with cloud state
3. (optional) restore  → Resolve NuGet deps in place (incl. authenticated Orchestrator feeds); login first
4. pack                → Produce deployable .zip package
5. login               → uip login (if not already authenticated)
6. publish             → Upload packed solution to UiPath
7. deploy run          → Promote to Orchestrator (auto-activates by default)
8. (optional) activate → Use --skip-activate on deploy, then activate explicitly

restore は最適化のためのものであり、必須ではありません。 pack は内部で依存関係を復元するため、別途 restore を実行するのは、依存関係を事前に解決しておきたい場合に限り有用です。多くの場合、CI で重い pack を実行する前にフィードの不足を早期に検出するため、login → restore → pack の順に実行します。restore に渡すのは <solutionPath> のみです（.uipx を含むソリューションディレクトリ、または .uis ファイル）。依存関係をその場で解決しますが、パッケージは生成しません。プライベートな Orchestrator フィードにアクセスするには認証済みセッションが必要なため、事前に uip login を実行してください。

ソリューションフロー内の AppV2 coded app は、uip codedapp から直接ではなく、uip solution を通じて処理します。 coded-app プロジェクトの .uipx に Type: "AppV2" が指定されている場合、uip solution pack はその .nupkg をバンドルし、uip solution deploy run はデプロイメントフォルダーにプロビジョニングします。別途 uip codedapp pack／publish／deploy を実行する必要はありません。スタンドアロンの coded app（npx create-vite を使ってソリューション外でスキャフォールドされ、プロジェクトルートにフラットな dist/ があり、project.uiproj／webAppManifest.json がないもの）には、代わりに直接 codedapp のパスを使用します。スタンドアロンのライフサイクル、およびソリューション内で uip codedapp init を使って AppV2 プロジェクトを作成する方法については、uipath-coded-apps を参照してください。

同じソースから、異なる2つの配布方法があります。

• pack → publish → deploy run — バージョン管理されたパッケージを Orchestrator に昇格します。
• upload — ブラウザー上でのデバッグのみを目的として、ソリューションを Studio Web に送信します。公開済みパッケージは生成されず、deploy run でデプロイすることもできません。

認証は前提条件です。作業を始める前に uip login status --output json を確認してください。ログインしていない場合は、ユーザーに uip login（対話型ブラウザーフロー）の実行を依頼してください。認証方法（対話型 OAuth、クライアント認証情報、テナントの切り替え）の詳細については、uipath-platform を参照してください。

このスキルは、SDD に基づくビルドの最終ステップです。uipath-planner が SDD を作成してタスクリストを導出し、実装スペシャリストがプロジェクトを構築した後、ここで .uipx をパックして出荷します。

既存のソリューションから開始する

Studio Web にすでにソリューションがある場合は、作り直すのではなく、そのソースをダウンロードしてください。

uip solution download <solution-id> --destination <dir> --extract --output json

• <solution-id> は Studio Web のソリューション GUID です。ユーザーから提示されていない場合は、ユーザーに確認してください。
• Data.ExtractedTo 内で作業してください。このディレクトリには .uipx とプロジェクトフォルダーが含まれています。まず、そこにある AGENTS.md／CLAUDE.md を読んでください。アーカイブにこれらのファイルがない場合、--extract が追加します。新しいフォルダーか空のフォルダーに展開してください。--extract は既存ファイルを上書きするため、編集済みのコピーに対して再実行すると、その変更が失われます。必ず事前にユーザーに確認してください。
• 展開された .uipx には Studio Web の SolutionId が保持されます。uip solution upload を実行すると、ログイン中の組織に同じ ID のソリューションがあれば上書きし、なければ新しいソリューションとしてインポートします（ソリューションの開発 § アップロード）。ソリューションを別の組織またはテナントに移動するには、その環境にログインして upload を実行するか、そこで pack → publish → deploy run を実行してください。

リファレンスのナビゲーション

ファイル	目的
ソリューションの概要	ソリューションとは何か、.uipx マニフェスト、ファイル構造、ライフサイクル図、コマンドツリー

| ソリューションの開発 | uip solution init / project add / import / remove / resources refresh / resources add / resources remove / resources edit、実環境で確認された注意点 |

| パッケージ化とデプロイ | restore / pack / publish / deploy run / feeds list、テナント以外のフィードを指定する方法（--feed / --personal-workspace）、デプロイ設定、CI/CD パイプラインのパターン | | 有効化と管理 | deploy activate / status / upgrade / uninstall / delete、インプレースでのバージョンアップグレード、環境管理 | | シナリオの一覧 | 失敗モードとエッジケース — 手動編集、共有リソース、仮想リソース、名前の衝突 |

アンチパターン

1. pack、publish、deploy run、activate に REST 呼び出しを独自実装すること。 uip solution CLI は、認証、フォルダーヘッダー、パイプラインのセマンティクス、ページネーションを正しく処理します。まず該当タスクを実行できるコマンドがないことを確認し、その後で REST を使用してください。
2. resources/solution_folder/ を直接編集すること。 これは自動生成され、自動的にクリーンアップされます。手動で編集すると .uipx との同期が崩れます。代わりに uip solution projects add/remove を使用してください。
3. pack または upload の前に uip solution resources refresh を実行しないこと。 古いバインディングやデバッグによる上書き状態がそのまま含まれます。
4. すでに .uipx に登録されている AppV2 プロジェクトに対して、uip codedapp pack / publish / deploy を実行すること。 Type: "AppV2" として登録された時点で、コード化アプリはソリューションの一部です。uip solution pack / uip solution publish / uip solution deploy run で処理してください。uip codedapp publish を直接実行すると、ソリューションのデプロイ設定（外部クライアント ID、ルーティング名、アクションスキーマ）が適用されず、登録が重複します。uip codedapp を直接使用するのは、npx create-vite でスキャフォールディングした単体のコード化アプリ（ツリー内に .uipx がなく、project.uiproj / webAppManifest.json もないもの）に限ってください。
5. デプロイ設定を使用せず、環境ごとに新しい .uipx を作成すること。 1 つのパッケージ化済みソリューションを、環境ごとの --config-file で開発／ステージング／本番へ昇格させ、uip login tenant set で対象テナントを指定できます。環境ごとに異なる .uipx ファイルを使うと、バージョン追跡ができなくなります。
6. uip solution upload（Studio Web）をデプロイ方法として使用すること。 アップロードはブラウザー上のデバッグ専用です。公開済みパッケージは生成されず、deploy run で昇格させることもできません。実際にデプロイする場合は pack → publish → deploy run を使用してください。また、upload したソリューションは Studio Web の Cloud workspace タブに配置され、Local タブには配置されません。SW の Local タブは別個の登録であり、uip solution からはアドレス指定できません。
7. 変更後に終了コードだけを信頼すること。 必ず成果物（project.json、.uipx、デプロイステータス）を確認してください。ゼロ以外の終了コードでも状態が一部変更されている場合があり、ゼロの終了コードでも警告が隠れていることがあります。