GitHub에서 워크스페이스로 플러그인을 가져오고 리포지터리의 변경 사항을 동기화해 플러그인을 최신 상태로 유지할 수 있습니다. 마켓플레이스는 가져올 플러그인 목록을 담은 JSON 파일입니다.
시작하기 전에
워크스페이스 관리자 권한이 필요합니다. 마켓플레이스 리포지터리와 이 리포지터리가 참조하는 모든 리포지터리를 읽을 수 있는 GitHub 계정을 사용하세요. 공개 및 비공개 GitHub 리포지터리를 모두 지원합니다. GitHub 조직에서 액세스 승인을 요구하는 경우 가져오기 전에 승인을 받으세요.
가져오기 전에 리포지터리를 검토하세요. 다음 기본 설정에 따라 멤버가 사용할 수 있는 플러그인이 달라집니다.
- 새 플러그인은 사용 가능 상태이므로 멤버가 설치할 수 있습니다. 인증이 필요하면 멤버가 플러그인을 설치할 때 인증을 완료합니다.
- 가져오기 시 유효한 항목을 모두 처리합니다. 새 마켓플레이스는 매일 자동으로 동기화되며, 리포지터리에 새로 추가된 플러그인도 가져옵니다.
이 가이드에서는 워크스페이스로 플러그인을 가져오는 방법을 설명합니다. 로컬 클라이언트의 경우 플러그인 마켓플레이스 및 기본값 구성에서 클라우드 관리 설정이나 시스템 config.toml 설정을 구성하는 방법을 확인하세요. 특정 프로젝트에 적용하려면 리포지터리에서 플러그인 활성화 또는 비활성화를 참고하세요.
마켓플레이스 동기화 구성
- 관리자 > 플러그인을 열고 추가 > 마켓플레이스 가져오기를 선택하세요.
- 소스에
https://github.com/example/team-plugins와 같은 리포지터리 URL을 입력하세요. 브랜치나 폴더를 가리키는 URL은 사용하지 말고 리포지터리 자체의 URL만 입력하세요. - 마켓플레이스가 하위 디렉터리에 있으면 경로에 해당 디렉터리를 입력하세요. 예를 들어
team-tools를 입력하면team-tools/.agents/plugins/marketplace.json을 사용합니다. 리포지터리 루트를 사용하려면 경로를 비워 두세요. 매니페스트 파일 이름은 입력하지 마세요. - 필요한 경우 브랜치, 태그 또는 커밋을 입력하세요. 비워 두면 리포지터리의 기본 브랜치를 사용합니다. 브랜치를 지정하면 이후 업데이트를 받을 수 있습니다. 특정 커밋을 지정하면 선택한 버전이 유지됩니다.
- 마켓플레이스 가져오기를 선택하고 메시지가 표시되면 GitHub 액세스를 승인하세요. 마켓플레이스 규모가 특히 크면 처음 가져올 때 최대 1시간이 걸릴 수 있습니다. 이후 매일 실행되는 동기화는 보통 몇 분이면 완료됩니다.
- 가져오기 결과를 검토한 다음, 가져온 플러그인을 하나씩 열어 설치 정책과 필요한 앱을 설정하세요.
지원 형식
선택한 디렉터리에는 다음 파일 중 하나가 있어야 합니다.
| 파일 | 형식 |
|---|---|
.agents/plugins/marketplace.json |
plugins 배열이 있는 Codex 마켓플레이스 |
.claude-plugin/marketplace.json |
plugins 배열이 있는 Claude 호환 마켓플레이스 |
.claude-plugin/plugin.json |
마켓플레이스 매니페스트가 없을 때 사용하는 독립형 Claude 플러그인 |
마켓플레이스 항목은 .codex-plugin/plugin.json이 있는 네이티브 플러그인, Claude 호환 플러그인, Agent Plugins 1.0 패키지 또는 지원되는 스킬 패키지를 참조할 수 있습니다.
Codex 마켓플레이스에서는 같은 리포지터리에 있는 플러그인을 로컬 경로로 지정하세요.
{
"name": "team-plugins",
"interface": {
"displayName": "Team plugins"
},
"plugins": [
{
"name": "team-tools",
"source": {
"source": "local",
"path": "./plugins/team-tools"
}
}
]
}경로는 선택한 마켓플레이스 루트를 기준으로 지정합니다. .agents/plugins/를 기준으로 지정하지 마세요.
Claude 호환 마켓플레이스에서는 각 로컬 플러그인의 경로를 문자열로 지정할 수 있습니다.
{
"name": "team-plugins",
"plugins": [
{
"name": "team-tools",
"source": "./plugins/team-tools"
}
]
}Codex 마켓플레이스 항목에서는 GitHub 리포지터리 루트에 있는 플러그인에 source: "url"을, GitHub 리포지터리의 하위 디렉터리에 있는 플러그인에 source: "git-subdir"을 사용할 수도 있습니다. 다음은 하위 디렉터리를 지정하는 예시입니다.
{
"name": "team-tools",
"source": {
"source": "git-subdir",
"url": "https://github.com/example/team-tools.git",
"path": "./plugins/team-tools",
"ref": "main"
}
}Git 소스에서는 ref 또는 40자리 전체 커밋 sha를 지정할 수 있습니다. 액세스를 승인하는 GitHub 계정에는 참조된 모든 리포지터리에 대한 읽기 권한이 있어야 합니다. 현재 워크스페이스로 플러그인을 가져올 때는 GitHub 리포지터리만 지원합니다.
워크스페이스 액세스 구성
각 플러그인의 설치 및 인증 설정은 워크스페이스에서 구성하세요. 가져오기와 동기화 과정에서는 리포지터리에 있는 설치 및 인증 설정을 적용하지 않습니다. 이러한 설정에는 AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL, ON_USE가 있습니다. 업데이트를 동기화하거나 GitHub에서 플러그인을 관리하도록 전환해도 기존 워크스페이스 설정은 유지됩니다.
설치 정책에서 적용 대상 역할별로 사용 가능 또는 설치됨을 선택하세요. 플러그인에 필요한 앱도 활성화하고 멤버가 연결된 서비스에 액세스할 수 있는지 확인하세요. 플러그인을 가져와도 멤버에게 앱 액세스 권한이 부여되거나 멤버 계정이 연결되지는 않습니다. 액세스 및 작업 설정을 선택하는 방법은 플러그인 제어를 참고하세요.
기존 플러그인을 GitHub에서 관리하도록 전환
기존 플러그인의 마켓플레이스 항목에 pluginId를 추가하세요.
{
"name": "team-tools",
"pluginId": "plugin_0123456789abcdef0123456789abcdef",
"source": {
"source": "local",
"path": "./plugins/team-tools"
}
}관리자 > 플러그인에서 해당 플러그인을 열고 URL의 /plugins/ 뒤에 있는 ID를 복사하세요. 마켓플레이스 항목에서 pluginId를 name, source와 같은 수준에 추가하세요. 기존 플러그인은 같은 워크스페이스에 있어야 하며, 항목의 name 값은 기존 플러그인의 이름과 일치해야 합니다.
아직 GitHub에서 관리하지 않는 워크스페이스 플러그인은 이 방법으로 GitHub에서 관리하도록 전환할 수 있습니다. 플러그인의 ID, 공유 설정, 워크스페이스 설정은 그대로 유지됩니다. 이후에는 GitHub에서 업데이트를 가져오므로 아카이브를 업로드해 플러그인을 교체할 수 없습니다. 다른 GitHub 소스에서 이미 관리하는 플러그인에는 이 방법을 사용할 수 없습니다.
데스크톱 전용 플러그인
데스크톱 전용으로 표시된 플러그인은 웹에서 ChatGPT를 사용할 때 실행할 수 없습니다. 가져온 플러그인이 MCP 서버를 선언하면 이 표시가 붙을 수 있습니다. 원격 HTTPS URL을 사용하는 서버도 여기에 해당합니다. .app.json 참조를 추가하는 것만으로는 표시가 사라지지 않습니다.
.app.json으로 기존 앱 참조
플러그인 루트에 .app.json을 추가하세요. 파일 이름은 점으로 시작해야 합니다. 점이 없는 app.json은 지원하지 않습니다.
{
"apps": {
"team-tools": {
"id": "asdk_app_example",
"required": true
}
}
}asdk_app_example을 기존 앱의 ID로 바꾸세요. 지원되는 앱 ID는 asdk_app_, connector_ 또는 templated_apps_로 시작합니다. 앱 ID를 사용해야 하며, plugin_... 형식의 ID는 사용할 수 없습니다. 예를 들어 플러그인 URL에 plugin_asdk_app_example이 포함되어 있다면 해당 앱의 ID는 asdk_app_example입니다.
team-tools 키는 이 파일 안에서 앱 참조에 붙인 이름입니다. 플러그인이 해당 앱에 의존하면 required를 true로 설정하세요. 항목을 더 추가해 다른 기존 앱도 참조할 수 있습니다.
네이티브 플러그인의 경우 apps 값을 ./.app.json으로 지정하세요. 이 설정은 .codex-plugin/plugin.json에 추가합니다. 다음은 이 예시의 전체 매니페스트입니다.
{
"name": "team-tools",
"version": "1.0.0",
"description": "Use the team's approved tools.",
"author": {
"name": "Example team"
},
"apps": "./.app.json",
"interface": {
"displayName": "Team tools",
"shortDescription": "Use approved team tools",
"longDescription": "Connect to the team's existing app.",
"developerName": "Example team",
"category": "Productivity",
"capabilities": ["Read"]
}
}파일은 다음 구조로 배치하세요.
team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
├── .codex-plugin/plugin.json
└── .app.json이 파일은 기존 앱을 참조합니다. 앱을 새로 만들거나 액세스 권한을 부여하지는 않습니다. 앱이 필요한 역할에서 앱을 사용할 수 있도록 설정하고, 인증이 필요하면 멤버에게 인증을 완료하도록 요청하세요. 앱의 권한, 허용된 작업, 연결된 서비스의 액세스 권한은 계속 적용됩니다.
플러그인을 최신 상태로 유지
새 마켓플레이스는 매일 업데이트를 확인합니다. 자동 동기화를 기다리지 않고 업데이트를 요청하려면 관리자 > 플러그인 > 마켓플레이스를 열고 해당 마켓플레이스를 선택한 다음 지금 동기화를 선택하세요.
동기화하면 마켓플레이스의 새 플러그인을 추가하고 기존 플러그인을 업데이트할 수 있습니다. 자동 동기화는 새 플러그인도 가져오므로 리포지터리 변경 사항을 병합하기 전에 검토하세요.
동기화할 때마다 상태와 저장된 보고서를 확인하세요. 동기화가 완료되어도 개별 플러그인에는 오류가 있을 수 있습니다. 업데이트가 유효하지 않으면 기존 플러그인은 마지막으로 정상 작동한 버전을 유지합니다. GitHub에서 문제를 수정한 다음 지금 동기화를 선택해 다시 시도하세요.
마켓플레이스에서 플러그인 항목을 제거해도 워크스페이스에는 해당 플러그인이 남으며 소스에 더 이상 없음으로 표시됩니다. 반면 ChatGPT에서 마켓플레이스를 삭제하면 해당 마켓플레이스에서 가져온 플러그인이 모두 삭제됩니다.
GitHub 계정 다시 연결 또는 액세스 변경
마켓플레이스 동기화에는 해당 마켓플레이스를 가져온 관리자의 GitHub 연결이 사용됩니다.
다시 연결하려면 먼저 마켓플레이스를 가져온 관리자의 GitHub 계정에 마켓플레이스 리포지터리와 이 리포지터리가 참조하는 모든 리포지터리에 대한 읽기 권한이 여전히 있는지 확인하세요. 그런 다음 해당 관리자가 ChatGPT에서 GitHub 플러그인을 열고 자신의 계정을 다시 연결해야 합니다.
소유자를 변경하려면 새 워크스페이스 관리자가 관리자 > 플러그인 > 추가 > 마켓플레이스 가져오기에서 마켓플레이스를 다시 가져와야 합니다. 소스, 경로, 브랜치, 태그 또는 커밋 값은 기존과 동일하게 입력하세요. 이후 동기화에는 새 관리자의 GitHub 연결이 사용됩니다.
계정을 다시 연결하거나 소유자를 변경할 때는 마켓플레이스를 그대로 유지하세요. 마켓플레이스를 삭제하면 여기에서 가져온 플러그인도 삭제됩니다.