Developer Console의 글로벌 브랜치

Developer Console은 글로벌 브랜치(Global branch)에서 OSDK 앱의 선택 리소스와 온톨로지 정의를 함께 개발할 수 있습니다. 같은 앱의 개발 서버와 PR 미리보기에서 브랜치 데이터를 읽고 액션을 시험할 수 있습니다.

지원 범위와 준비

이 통합은 npm으로 설치한 TypeScript SDK 및 Vite 6, 7 또는 8 앱을 지원합니다. 다른 SDK 언어나 패키지 매니저에는 적용하지 않습니다.

시작 조건은 다음과 같습니다.

• 앱은 프로젝트에 있어야 합니다. 기존 앱은 Compass 권한 이전을 수행합니다.
• 앱에는 main에서 이미 OSDK가 있어야 합니다. 글로벌 브랜치에서 처음 SDK를 추가할 수 없습니다.
• 글로벌 브랜치는 앱 SDK와 같은 온톨로지를 사용해야 합니다.
• 저장소 템플릿, 패키지와 Vite 설정을 기본 브랜치에 먼저 반영해야 합니다.
• 액션이 편집하는 모든 객체 유형을 브랜치에 인덱싱하고 완료를 기다려야 합니다. 브랜치에서 만든 테스트 편집은 main에 병합하지 않습니다.

설정이 빠지면 앱이 경고 없이 main 또는 다른 브랜치의 데이터를 읽거나 편집할 수 있습니다. Git 브랜치만 만드는 것으로 글로벌 브랜치 문맥을 만들지는 않습니다.

접근 제한은 브랜치 공통

앱 접근 제한은 main을 포함한 모든 브랜치에서 공유합니다. 비기본 브랜치에서는 필요한 온톨로지 리소스를 추가할 수 있지만 제거할 수 없습니다. Platform SDK 프로젝트, 작업 제한, 보안 표지 제한과 OAuth 설정은 읽기 전용입니다.

오래된 리소스 정리는 main의 OAuth & restrictions > Restrictions & access > Review resources에서 합니다. 다른 SDK 버전이나 브랜치가 쓰지 않는지 확인하고 Remove resources를 선택합니다.

같은 글로벌 브랜치에서 SDK 생성

Developer Console의 브랜치 선택기에서 기존 글로벌 브랜치를 고르거나 새로 만듭니다.

같은 브랜치에서 온톨로지를 변경한 뒤 Ontology SDK > Resources에서 선택 엔터티를 갱신합니다. SDK versions > Generate new version을 실행하면 앱이 아직 브랜치 구성원이 아닌 경우에도 브랜치에 추가됩니다.

소스 저장소도 같은 글로벌 브랜치로 체크아웃한 뒤 npm install을 실행합니다. postinstall의 osdk branch sync가 그 브랜치의 최신 SDK 의존성을 동기화하므로 버전 문자열을 손으로 복사할 필요는 없습니다. 변경된 package.json과 package-lock.json을 검토하고 커밋 및 push합니다.

개발 서버

저장소의 Branches > New branch > Global branch에서도 글로벌 브랜치를 만들 수 있습니다. 로컬 AI 도구에서는 Palantir MCP의 create_global_branch를 사용할 수 있습니다.

VS Code 작업 공간은 개발 서버를 시작할 때 npm install을 먼저 실행합니다. 서버를 시작한 뒤 브랜치를 바꿨다면 미리보기 도구 모음의 추가 작업에서 Restart development server를 선택하여 의존성을 다시 설치합니다.

로컬 복제본은 Foundry가 글로벌 브랜치에 대해 만든 저장소 브랜치를 fetch하고 같은 Git 이름으로 체크아웃해야 합니다. Code Repositories 브랜치 선택기의 정보 아이콘에서 Working locally on a global branch의 이름을 확인합니다. 플러그인과 osdk branch sync는 현재 Git 브랜치 이름으로 문맥을 결정합니다.

npm install && npm run dev

제안과 PR 미리보기

글로벌 브랜치의 제안(Proposal)을 만들면 코드 저장소 PR이 생깁니다. 지원 템플릿과 호스팅 구성을 갖춘 경우 CI가 브랜치에 읽기와 쓰기를 수행하는 PR 미리보기를 배포합니다.

1. 글로벌 브랜치의 제안을 만듭니다.
2. 연결된 코드 PR을 엽니다.
3. 앱 publish 검사가 성공하면 Preview를 선택합니다.
4. 해당 브랜치에만 있는 변경을 확인하고 브라우저 네트워크 도구에서 온톨로지 요청의 branch 질의 매개변수가 목표 글로벌 브랜치 RID인지 확인합니다.

글로벌 브랜치에서는 릴리스 태그나 프로덕션 웹사이트 게시를 할 수 없습니다. 제안의 미리보기 URL을 검토자에게 공유하고, 병합 뒤 기본 브랜치에서 릴리스해야 합니다.

Workshop의 양방향 Iframe

OSDK 앱 안에 다른 OSDK 앱을 임베드하는 구성은 글로벌 브랜치를 지원하지 않습니다. 자식이 호스트 문맥을 상속하지 않아 main을 편집할 수 있습니다.

Workshop에서는 Iframe 위젯의 Bidirectional 구성만 다음 조건으로 지원합니다.

• 앞의 저장소 준비를 모두 마칩니다.
• 앱과 Workshop의 양방향 통신을 설정하고 Iframe의 Bidirectional을 선택합니다.
• @osdk/client 2.77.0 이상을 사용합니다.
• createPublicOauthClient의 옵션에 useHistory: false를 넣고 기존 scopes 등 다른 옵션을 유지합니다.
• OSDK 클라이언트에 명시적인 branch override를 전달하지 않습니다.

import { createClient } from "@osdk/client";
import { createPublicOauthClient } from "@osdk/oauth";

export function createWorkshopClient(
    clientId: string, foundryUrl: string, redirectUrl: string, ontologyRid: string, scopes: string[]
) {
    const auth = createPublicOauthClient(clientId, foundryUrl, redirectUrl, { scopes, useHistory: false });
    return createClient(foundryUrl, ontologyRid, auth);
}

이는 사용자 지정 위젯 통합의 지원을 뜻하지 않습니다. 새 위젯은 별도 Custom widgets 경로를 검토합니다.

Workshop 브랜치를 바꾸어도 iframe URL의 배포 자산과 포함 SDK가 새로 빌드되지는 않습니다. 따라서 그 웹사이트가 쓰는 객체, 속성과 액션의 스키마는 시험할 브랜치에서 호환되어야 합니다. 비호환 변경을 시험하려면 새 SDK와 앱을 배포하고 그 호환 URL을 iframe에 연결합니다.

준비 변경을 저장소 기본 브랜치로 병합하고 릴리스한 뒤 해당 웹사이트를 임베드합니다. Workshop 브랜치 미리보기에서 실제 온톨로지 요청의 branch가 목표 RID인지 확인해야 합니다. 조건을 충족하지 않으면 main에 요청할 수 있습니다.

기존 저장소 이전

먼저 기본 브랜치에서 만든 코드 브랜치에 템플릿 및 수동 앱 변경을 적용합니다. 글로벌 브랜치에 추가하기 전에 기본 브랜치로 병합해야 합니다. Foundry의 지원 검사는 저장소 master 브랜치의 package-lock.json과 루트 vite.config.ts를 보며 master가 보통 기본 브랜치입니다.

템플릿 업그레이드

Ontology SDK React Application 템플릿 osdk-react-app-v2는 0.291.0 이상이 필요합니다. 다른 지원 템플릿은 최신으로 올리고 그 템플릿별 최소 버전 검사를 따릅니다. npm 의존성만 바꾸면 템플릿 조건을 충족하지 못합니다.

기본 브랜치에서 Upgrade를 열고 templateConfig.json의 parentTemplateId 및 parentTemplateVersion을 검토한 뒤 필요한 업그레이드 PR을 적용합니다.

템플릿은 ci.yml과 .jemma/sync-sdk-dependencies.sh를 제공합니다. 이후 템플릿 업그레이드가 관리 파일을 덮어쓸 수 있으므로 제공된 파일을 사용합니다. 기존 package.json, package-lock.json과 vite.config.ts는 자동 변경하지 않으므로 아래 수동 설정도 필요합니다. OSDK 1.x 기반 템플릿은 지원하지 않습니다.

패키지와 postinstall

기존 package.json의 다른 의존성과 스크립트를 유지하며 다음 항목을 병합합니다. 이미 postinstall이 있으면 osdk branch sync를 기존 명령과 함께 실행하도록 연결합니다.

{
  "scripts": {
    "postinstall": "osdk branch sync"
  },
  "dependencies": {
    "@osdk/client": "^2.77.0",
    "@osdk/vite-plugin-branch": "^2.77.0"
  },
  "devDependencies": {
    "@osdk/cli": "latest"
  }
}

생성 SDK 의존성도 유지합니다. npm install의 동기화가 현재 브랜치용 버전으로 갱신합니다.

정확한 Vite 설정 형태

지원 검사는 루트의 vite.config.ts만 인식합니다. branchPlugin을 named import로 가져오고 inline plugins 배열에 직접 branchPlugin()을 호출해야 합니다. vite.config.js, vite.config.mts 또는 helper/변수로 만든 plugins 배열은 이 검사에서 인식하지 않습니다.

import { branchPlugin } from "@osdk/vite-plugin-branch";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), branchPlugin()], // Preserve your other plugins.
  // Preserve your other configuration settings.
});

기존 VS Code 작업 공간 설정과 다른 플러그인을 그대로 유지합니다.

설치와 확인

npm install로 lock 파일과 SDK 의존성을 갱신한 뒤 앱 파일과 템플릿 CI 파일을 커밋합니다. 앱의 기존 검사와 빌드를 수행하고 기본 브랜치로 병합합니다. 그다음 글로벌 브랜치에 저장소를 추가하고 해당 브랜치에서 npm install을 다시 실행합니다.

Unable to add this repository to a global branch, This repository is not set up for Global branching 또는 This repository template does not support Global branching 오류가 나면 다음을 확인합니다.

• 템플릿 자체가 지원되는 최소 버전인지 확인합니다.
• package-lock.json의 실제 패키지 버전이 조건을 만족하는지 확인합니다.
• 루트 vite.config.ts가 요구 형태인지 확인합니다.
• 수정이 검사 대상 master 브랜치에 반영되었는지 확인합니다.

개발 서버에서 브랜치 전용 데이터를 보고 네트워크 요청의 branch 이름 또는 RID를 확인합니다. 새 SDK 생성 뒤 설치한 버전도 Developer Console의 브랜치 최신 버전과 비교합니다.

검토, rebase와 배포

제안의 Changes에서 앱을 선택하여 SDK 리소스 추가와 제거를 검토합니다.

main의 리소스가 바뀌어 충돌하면 Ontology SDK의 Start rebase를 엽니다. Main과 브랜치를 비교하고 Keep this version을 선택합니다. 이 선택은 개별 엔터티가 아니라 해당 쪽의 전체 리소스 집합을 유지합니다.

Rebase and save 뒤 브랜치 SDK를 다시 생성하고 npm install로 소스 의존성을 갱신합니다. package.json과 lock 파일을 커밋하고 앱을 다시 확인해야 합니다. 제안 검사는 최신 리소스로 생성한 SDK를 요구합니다.

제안을 main으로 병합하는 것만으로 프로덕션 웹사이트를 배포하지 않습니다. 병합 후 기본 브랜치에서 릴리스와 호스팅을 수행합니다.