Developer Console アプリケーションをブランチ化する

Developer Console は Global Branching と統合されており、オントロジーリソースへの変更と並行して、オントロジー SDK（OSDK）の React アプリケーションを開発できます。グローバルブランチでは、SDK に含めるリソースの変更、ブランチ化されたオントロジー定義からの SDK の生成、ブランチ上のデータに対するアプリケーションのテストを行えます。

機能

グローバルブランチ上で Developer Console を使用すると、次のことができます。

• 生成する SDK に含めるリソースを変更する。
• ブランチ化されたオントロジーリソースの定義に基づいて SDK を生成する。
• 新しい SDK を生成せずに、グローバルブランチからデータを読み取る。
• ブランチ化された SDK を使用して開発する。
• 開発サーバーまたはプルリクエストのプレビューから、ブランチのデータを読み書きする。

新しい SDK を生成する必要があるかどうかは、テストする変更によって異なります。

いずれの場合も、ブランチ上でアクションをテストする前に、インデックス化の前提条件を満たしてください。

制限事項

Developer Console の統合は、Vite 6、7、または 8 を使用するアプリケーションで、npm によってインストールされた TypeScript SDK に対応しています。現在、ほかの SDK 言語やパッケージマネージャーには対応していません。

Global Branching は、ほかのオントロジー SDK アプリケーション内に埋め込まれたオントロジー SDK アプリケーションには対応していません。埋め込みアプリケーションはホストアプリケーションのブランチコンテキストを継承せず、main にアクションを適用するリクエストを送信する可能性があります。埋め込みアプリケーションで Global Branching を利用できるのは、必要なクライアントバージョンとオプションを使用した双方向の Workshop Iframe ウィジェット設定を通じてのみです。

前提条件

グローバルブランチ上で開発する前に、次の前提条件を満たしてください。

• Developer Console アプリケーションがプロジェクト内にあることを確認してください。レガシーアプリケーションの場合は、権限変更に関するガイダンスを含め、プロジェクトの移行手順に沿って進めてください。
• ワークフロー用のグローバルブランチを作成または選択します。グローバルブランチ上ではオントロジー SDK を追加できないため、Developer Console アプリケーションには、main 上ですでにオントロジー SDK が存在している必要があります。グローバルブランチでは、アプリケーションの SDK と同じオントロジーを使用する必要があります。
• Vite 6、7、または 8 とともに、対応する依存関係のバージョンを使用してください。ブランチ化を設定する前に、古い Vite バージョンと影響を受けるプラグインをアップグレードしてください。アプリケーションで OSDK 1.x を使用している場合は、まず TypeScript オントロジー SDK 移行ガイドに沿って進めてください。
• Foundry のコードリポジトリでは、Global Branching に対応し、テンプレートの最小バージョン要件を満たすテンプレートを使用してください。たとえば、Ontology SDK React Application テンプレート（osdk-react-app-v2）の最新バージョンから作成されたリポジトリには、必要な依存関係と Vite の設定がすでに含まれています。
• リポジトリで古いバージョンのテンプレートを使用している場合、または必要な設定がない場合は、テンプレートのアップグレードから始めて、既存のリポジトリを移行するの手順に沿って進めてください。リポジトリをグローバルブランチに追加する前に、変更をデフォルトブランチにマージしてください。
• アクションをテストする前に、そのアクションによって編集されるすべてのオブジェクトタイプをグローバルブランチ上でインデックス化してください。複数のオブジェクトタイプを一度にインデックス化するには、Workflow Lineage での一括インデックス化を使用します。インデックス化が完了するまで待ってから、アクションを実行してください。ブランチ上でのアクションの実行はテスト専用です。ブランチ上でアクションによって行われた編集は、main にはマージされません。

ブランチ間でのアプリケーションの制限

アプリケーションの制限は、デフォルトブランチである main を含むすべてのブランチで共有されます。これらの制限への変更は、すべてのブランチ上のアプリケーションに影響します。

デフォルト以外のブランチでは、そのブランチに必要なオントロジーリソースのみをリソース制限に追加できます。制限を削除すると main を含むほかのブランチが正常に動作しなくなる可能性があるため、制限を削除することはできません。プラットフォーム SDK タブのプロジェクト制限、操作制限、マーキング制限、および OAuth クライアント設定は、デフォルト以外のブランチでは読み取り専用です。

使用されていないリソース制限を確認する

現在の SDK に含まれなくなったリソースの制限を確認するには、次の手順を実行します。

1. Developer Console でアプリケーションを開き、main に切り替えます。
2. ［OAuth と制限］ページを開き、制限とアクセスタブを選択します。
3. リソースを確認するを選択して、古い SDK リソースを確認ダイアログを開きます。
4. 一覧に表示されたリソースを確認し、不要になったものを選択します。別の SDK バージョンまたはブランチでまだ使用されているリソースを削除すると、そのブランチ上のアプリケーションが正常に動作しなくなる可能性があります。
5. リソースを削除を選択します。

グローバルブランチで開発する

Developer Console のアプリケーション、そのオントロジーの変更、およびソースコードには、同じグローバルブランチを使用します。グローバルブランチは Foundry 全体のリソースを連携させます。Git ブランチだけでは、そのコンテキストは確立されません。

ブランチでアプリケーションを開く

1. Developer Console でアプリケーションを開きます。
2. ブランチセレクターを使用して、ワークフロー用のグローバルブランチを作成するか、そのブランチに切り替えます。
3. SDK に含めるリソースを変更する前に、選択されているブランチを確認します。
4. アクションをテストする前に、前提条件の説明に従い、それらのアクションが編集するすべてのオブジェクトタイプでインデックス化が完了していることを確認します。

一般的なブランチの操作については、ブランチを作成またはアクセスするを参照してください。

リソースを更新して SDK を生成する

SDK に含めるリソースを変更し、ブランチ上のオントロジー定義から SDK を生成するには、次の手順を実行します。

1. 同じグローバルブランチで、必要なオントロジーの変更を行います。オントロジーをブランチ化するを参照してください。
2. Developer Console でオントロジー SDK ページを開き、リソースタブを選択して、アプリケーションの SDK に含めるリソースを更新します。
3. SDK バージョンタブを開き、新しいバージョンを生成するを選択して、ブランチ上で SDK バージョンを生成します。Developer Console アプリケーションがまだグローバルブランチに含まれていない場合、SDK を生成すると、そのブランチに追加されます。
4. アプリケーションリポジトリで同じグローバルブランチをチェックアウトし、npm install を実行して、そのブランチで生成された最新の SDK を使用します。
5. 更新された package.json ファイルと package-lock.json ファイルを確認し、コミットしてプッシュします。これにより、提案のチェックとプレビュービルドで、更新された SDK の依存関係が使用されます。

リポジトリの postinstall スクリプトが SDK の依存関係を同期します。ブランチ上の SDK バージョンを package.json に手動でコピーする必要はありません。

開発サーバーを実行する

開発を開始する前に、リポジトリのセットアップを完了してください。ワークフロー用のグローバルブランチがまだ存在しない場合は、コードリポジトリから作成できます。ブランチタブを開き、新規ブランチ名を選択して、グローバルブランチを選択します。ローカル開発環境から Palantir MCP の Global Branching ツールを使用して、グローバルブランチを作成することもできます。ローカルの Git ブランチを作成するだけでは、グローバルブランチは作成されません。

VS Code ワークスペースを使用する

Foundry でホストされている VS Code ワークスペースを開き、ワークフロー用のグローバルブランチをチェックアウトします。ワークスペースで開発サーバーを起動するたびに、生成された設定によって最初に npm install が実行されます。インストール中に、postinstall スクリプトがアプリケーションの SDK の依存関係を、チェックアウトしたブランチで生成された最新の SDK と同期します。開発サーバーの起動後にブランチをチェックアウトした場合は、プレビューツールバーの追加アクションメニューを開き、開発サーバーを再起動を選択して依存関係を再インストールします。

ローカル開発環境を使用する

グローバルブランチがまだ存在しない場合は、Foundry で作成するか、ローカルの AI 開発ツールで Palantir MCP を通じて create_global_branch ツールを使用します。Developer Console アプリケーションと同じオントロジーを使用します。ブランチや提案を作成および調査するためのツールについては、Global Branching ツールのリファレンスを参照してください。

リソースのブランチ化ワークフローに従い、ソースコードリポジトリが同じグローバルブランチ上にあることを確認してください。ローカルクローンで、Foundry がそのグローバルブランチ用に作成したリポジトリブランチをフェッチしてチェックアウトし、ローカルでも同じ Git ブランチ名を保持します。この名前を確認するには、Code Repositories でグローバルブランチを開き、ブランチセレクターの情報アイコンにカーソルを合わせます。ポップオーバーのグローバルブランチでローカル作業するの下に、Code Repositories のブランチ名が表示されます。ブランチプラグインと osdk branch sync は、チェックアウトされている Git ブランチ名を使用してブランチのコンテキストを特定します。次に、依存関係をインストールしてローカル開発サーバーを起動します。

Copied!
1
2
npm install
npm run dev

ローカルで npm install を実行すると、同じ postinstall スクリプトが呼び出され、アプリケーションが、チェックアウトしたグローバルブランチで生成された最新の SDK と同期されます。

どちらの環境でも、SDK の生成とインデックス化の要件を満たしていれば、開発サーバーはグローバルブランチのデータを読み取り、アクションを適用できます。

プルリクエストをプレビューする

グローバルブランチの提案を作成すると、ソースコードのプルリクエストが作成されます。その後、継続的インテグレーション（CI）ビルドによって、グローバルブランチの読み書きを行うプルリクエストプレビューがデプロイされます。プレビューには、Global Branching をサポートするリポジトリテンプレート、必要なアプリケーション設定、および Developer Console でアプリケーション用に設定された［Web サイトホスティング］が必要です。プレビューをほかのユーザーと共有して、ブランチ上のオントロジーリソースとともにアプリケーションをテストします。

1. グローバルブランチの提案を作成します。
2. 提案に対して作成されたコードリポジトリのプルリクエストを開きます。
3. アプリケーションの公開チェックに成功したら、チェックの横にあるプレビューを選択します。
4. プレビューを開き、意図したグローバルブランチでのみ利用可能な変更またはデータが表示されることを確認します。ブラウザーのネットワークツールで、アプリケーションのオントロジーリクエストに、グローバルブランチのリソース識別子（RID）を含む branch クエリパラメーターが含まれていることを確認します。その後、プレビュー URL をレビュー担当者と共有します。

Workshop で埋め込みアプリケーションを使用する

この統合では、Workshop の iframe ウィジェットの双方向設定のみをサポートしています。iframe ウィジェットのドキュメントでは、新しい統合にカスタムウィジェットを推奨していますが、この統合はカスタムウィジェットには対応していません。

Workshop に埋め込まれた Developer Console アプリケーションは、次のすべての要件を満たす場合に Global Branching をサポートします。

• アプリケーションのリポジトリがリポジトリのセットアップの前提条件を満たしている。
• アプリケーションに Workshop との双方向通信が設定されており、iframe ウィジェットで双方向の選択肢が使用されている。
• アプリケーションが @osdk/client のバージョン 2.77.0 以降を使用している。
• アプリケーションが @osdk/oauth の createPublicOauthClient を初期化するときに、オプションで useHistory: false を渡している。
• オントロジー SDK クライアントが明示的なブランチのオーバーライドを渡していない。

scopes などの既存の OAuth オプションを維持したまま、OAuth クライアントに useHistory: false を設定します。

Copied!
1
2
3
4
5
6
const auth = createPublicOauthClient(clientId, foundryUrl, redirectUrl, {
  scopes,
  useHistory: false,
});

const client = createClient(foundryUrl, ontologyRid, auth);

グローバルブランチ上で Workshop モジュールをプレビューすると、双方向 iframe がそのブランチのコンテキストを埋め込みアプリケーションに渡します。iframe は引き続き、設定された URL にデプロイされている Web サイトを、そのデプロイにバンドルされた SDK も含めて読み込みます。Workshop のブランチを切り替えても、SDK の再生成や Web サイトの再ビルド、再デプロイは行われません。

そのため、デプロイされた Web サイトが使用するオントロジーのスキーマは、プレビューするブランチ間で安定している必要があります。Web サイトが使用するすべてのオブジェクトタイプ、プロパティ、アクションタイプ、その他のリソースは、バンドルされた SDK に対応している必要があります。互換性のないスキーマ変更をテストするには、その変更に対応する SDK を生成し、アプリケーションを更新して、対応するデプロイを iframe の参照先に設定します。

このセクションの要件を満たし、リポジトリのセットアップを完了したら、必要なアプリケーションとリポジトリの変更をリポジトリのデフォルトブランチにマージします。次に、リリースを作成して変更をデプロイします。その後、本番環境の Web サイトを iframe ウィジェットに埋め込むことができます。

ブランチのコンテキストを確認するには、グローバルブランチ上で Workshop モジュールをプレビューします。ブラウザーのネットワークツールで、埋め込みアプリケーションのオントロジーへのリクエストに、グローバルブランチの RID を含む branch クエリパラメーターが含まれていることを確認します。

既存のリポジトリを移行する

Code Repositories の対応する React アプリケーションテンプレートでは、リポジトリテンプレートをアップグレードして CI の変更を取得してから、アプリケーションの依存関係と Vite の設定を手動で更新します。テンプレートのアップグレードでは、アプリケーションコードや依存関係ファイルは変更されません。

デフォルトブランチから作成した Code Repositories のブランチで、手動の変更を行います。リポジトリをグローバルブランチに追加する前に、テンプレートのアップグレードと手動の変更をデフォルトブランチにマージします。Foundry は、リポジトリの master ブランチ（通常はデフォルトブランチ）にある package-lock.json と vite.config.ts を確認し、そのリポジトリが Global Branching に対応しているかどうかを判定します。

リポジトリテンプレートをアップグレードする

Foundry は、リポジトリのテンプレートバージョンが、そのテンプレートで Global Branching に対応するために必要な最小バージョンを満たしているか確認します。npm の依存関係を更新するだけでは、このテンプレート要件は満たされません。

Ontology SDK React Application テンプレート（osdk-react-app-v2）では、バージョン 0.291.0 以降を使用してください。以下の例では、このテンプレートを使用します。ほかの対応するアプリケーションテンプレートでは、利用可能な最新バージョンにアップグレードしてください。Foundry は、テンプレートごとに最小バージョンを個別に確認します。

1. Code Repositories でリポジトリを開き、デフォルトブランチを選択します。
2. 手動でのブランチアップグレードの説明に従って、リポジトリメニューからアップグレードを選択します。
3. templateConfig.json でアップグレードによる変更を確認します。parentTemplateId が使用しているテンプレートを示していることと、新しい parentTemplateVersion がそのテンプレートの Global Branching の最小バージョンを満たしていることを確認します。
4. 必要なアップグレードのプルリクエストのマージも含めて、リポジトリのアップグレードを適用します。詳細は、リポジトリのアップグレードを参照してください。

次のアップグレードのプルリクエストは、osdk-react-app-v2 を 0.271.0 から 0.291.0 に更新します。

対応する React アプリケーションテンプレートでは、アップグレードによって ci.yml が更新され、.jemma/sync-sdk-dependencies.sh が追加されます。これらのファイルは、ブランチコンテキストをビルドに渡し、プルリクエストのプレビューを設定し、提案のマージ時に SDK の依存関係を同期します。テンプレートで提供されるファイルを使用してください。後続のアップグレードによって、テンプレート管理ファイルが上書きされる場合があります。

アップグレードでは、既存のリポジトリの package.json、package-lock.json、vite.config.ts は変更されません。テンプレートのアップグレードに成功した後も、以下の手動の手順を完了してください。

TypeScript オントロジー SDK 1.x ベースのテンプレートは、この統合に対応していません。Global Branching に対応したオントロジー SDK 2.x ベースのテンプレートを使用し、アプリケーションコードについては TypeScript オントロジー SDK 移行ガイドに従ってください。

依存関係とスクリプトを更新する

Vite 6、7、8 では、次のバージョンの依存関係を使用してください。

CLI のバージョン 0.104.0 では、postinstall スクリプトで使用する osdk branch sync コマンドが導入されています。

次のエントリを既存の package.json にマージします。ほかの依存関係とスクリプトは保持してください。すでに postinstall スクリプトがある場合は、既存のコマンドに加えて SDK 同期コマンドを含めます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "scripts": {
    "postinstall": "osdk branch sync"
  },
  "dependencies": {
    "@osdk/client": "^2.77.0",
    "@osdk/vite-plugin-branch": "^2.77.0"
  },
  "devDependencies": {
    "@osdk/cli": "latest"
  }
}

アプリケーションの生成済み SDK の依存関係は、package.json 内に保持してください。npm install を実行すると、同期コマンドがアクティブなブランチに合わせてその依存関係を更新します。

Workshop に埋め込まれた双方向アプリケーションでは、createPublicOauthClient の初期化時に、オプションで useHistory: false も渡します。

ブランチプラグインを登録する

リポジトリのルートにある vite.config.ts ファイルを使用してください。@osdk/vite-plugin-branch から branchPlugin を名前付きでインポートし、インラインの plugins: [...] 配列内で branchPlugin() を直接呼び出します。Foundry の Global Branching の設定チェックでは、この構成が必須です。vite.config.js、vite.config.mts、および別の変数やヘルパーを通じて渡されるプラグイン配列は認識されません。

Foundry でホストされる VS Code ワークスペースの設定も含め、ほかのプラグインと設定は保持してください。次の例では、React プラグインとともにこのプラグインを使用しています。

Copied!
1
2
3
4
5
6
7
8
import { branchPlugin } from "@osdk/vite-plugin-branch";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), branchPlugin()], // ほかのプラグインはそのまま保持します。
  // ほかの設定はそのまま保持します。
});

依存関係をインストールして移行を確認する

ファイルを更新した後、VS Code ワークスペースまたはローカルクローンで、移行に使用した Code Repositories のブランチをチェックアウトし、次のコマンドを実行します。

Copied!
1
npm install

これにより、必要なパッケージがインストールされ、postinstall スクリプトが実行され、package-lock.json が更新されます。package.json、package-lock.json、vite.config.ts に対するアプリケーションの変更を確認してコミットします。リポジトリのアップグレードで提供された、テンプレート管理の CI ファイルと同期ファイルは保持してください。アプリケーションの既存の Linter による解析、テスト、ビルドのチェックを実行してから、移行の変更をリポジトリのデフォルトブランチにマージします。

移行の変更をマージした後、リポジトリをグローバルブランチに追加します。

Foundry に Unable to add this repository to a global branch: と表示された場合は、一覧に示されている理由を確認してください。VS Code では、エラーの詳細は This repository is not set up for Global branching: または This repository template does not support Global branching で始まります。リポジトリテンプレートが対応していないというメッセージが表示された場合は、リポジトリテンプレートをアップグレードします。依存関係または Vite に関するエラーの場合は、package-lock.json の依存関係のバージョンと、ルートの vite.config.ts の設定を確認します。リポジトリを再度追加する前に、修正がリポジトリの master ブランチに反映されていることを確認してください。

リポジトリを追加した後、グローバルブランチをチェックアウトし、npm install を再度実行して、その SDK の依存関係を同期します。開発サーバーを起動し、次のことを確認します。

• 開発サーバーに、対象のブランチでのみ利用可能な変更またはデータが表示されること。ブラウザーのネットワークツールで、アプリケーションのオントロジーへのリクエストを調べます。その branch クエリパラメーターに、対象のブランチの名前または RID が含まれていることを確認します。
• ブランチで SDK を生成して npm install を実行した後、インストールされた SDK のバージョンが、Developer Console のそのブランチに表示される最新バージョンと一致すること。

プレビューデプロイを確認するには、提案を作成し、そのプルリクエストをプレビューします。

変更をレビューしてマージする

Global Branching では、変更を main にマージする前に、提案でレビューします。一般的なワークフローについては、提案を作成して準備するを参照してください。

提案を開くと、ソースコードのプルリクエストが作成されます。そのプレビューデプロイを共有し、レビュー担当者がマージ前にグローバルブランチに対してアプリケーションをテストできるようにします。提案をマージしても、本番環境の Web サイトはデプロイされません。マージした変更をデプロイするには、リポジトリのデフォルトブランチでリリースを作成します。

提案の変更タブで Developer Console アプリケーションを選択し、その SDK に追加されたリソースや SDK から削除されたリソースをレビューします。

リベース時に競合を解決する

開発中に main 上のリソースが変更された場合は、Global Branching のリベースと競合解決に関するガイダンスを確認してください。

アプリケーションの SDK リソースの競合を解決するには、次の手順に従います。

1. Developer Console のオントロジー SDK ページで、リベースを開始を選択してアプリケーション SDK のリベースダイアログを開きます。
2. メインとこのブランチのリソースを比較し、保持するリソース群に対してこのバージョンを保持するを選択します。このバージョンを保持するは、選択した側のリソース群全体に適用されます。
3. リベースして保存を選択します。
4. ブランチで新しい SDK を生成し、ソースコードリポジトリで npm install を実行して SDK の依存関係を更新します。
5. 更新した package.json ファイルと package-lock.json ファイルをコミットしてプッシュし、アプリケーションを再テストします。

Developer Console の提案チェックでは、最新のアプリケーション SDK リソースから生成された SDK が必要です。