GitHub 아카이빙 가이드

synapse plugin publish 명령으로 플러그인을 배포하면, SDK가 플러그인 소스 코드를 GitHub에 자동으로 아카이빙할 수 있습니다 — 리포지토리(repository) 생성, 코드 푸시, 버전 태그 부여, ZIP 자산이 포함된 GitHub 릴리스 생성까지 한 번에 처리합니다.

플러그인 라이프사이클 컨텍스트

synapse plugin CLI는 플러그인을 스캐폴딩부터 배포까지 안내합니다. 아카이빙(Archiving) 은 모든 릴리스에 버전이 부여된, 변경 불가능한 소스 오브 트루스(source-of-truth)를 GitHub에 남기는 라이프사이클 단계로, 런타임 백엔드에 배포하는 단계와는 구분됩니다.

#	단계	CLI	동작
1	Create	`synapse plugin create`	새 플러그인 디렉토리를 대화형으로 스캐폴딩합니다.
2	Develop	`synapse plugin run`, `synapse plugin test`	로컬 실행과 반복적 테스트를 수행합니다.
3	Configure	`synapse plugin update-config`	액션을 자동 발견하여 `config.yaml`을 동기화합니다.
4	Validate	`synapse plugin publish --dry-run`, `--debug`	업로드 없이 미리보기; debug 모드는 백엔드 검증을 우회합니다.
5	Publish	`synapse plugin publish`	Synapse 백엔드(런타임 레지스트리)에 ZIP을 업로드합니다.
6	Archive	`synapse plugin publish` (배포 후 단계)	GitHub 설정이 있을 때, 소스를 GitHub 리포지토리에 미러링하고 태그를 달고 릴리스를 생성합니다. 옵트인(opt-in)이며 비차단(non-blocking)입니다.
7	Distribute	`synapse plugin publish -m plugin.yaml`, `synapse plugin package -m plugin.yaml [--offline]`	매니페스트 기반 일괄 배포 / 패키징을 GitHub 아카이빙된 릴리스로부터 수행합니다.

아카이브가 별도 단계인 이유

GitHub 아카이빙은 단순히 배포의 부수효과가 아니라 그 자체로 라이프사이클 단계입니다. 다음과 같은 가치를 제공하기 때문입니다:

릴리스별 변경 불가능한 소스 오브 트루스. 백엔드에 업로드된 동일한 ZIP이 GitHub 릴리스의 자산으로 첨부됩니다.
변형(variant) 브랜치 격리. 고객별 또는 배포 환경별로 커스터마이징된 빌드는 variant/{name} 브랜치와 {version}+{variant} 태그로 메인 릴리스 라인과 격리됩니다.
매니페스트 기반 배포의 해석 기준. synapse plugin publish -m plugin.yaml 과 synapse plugin package -m plugin.yaml 은 로컬 체크아웃이 아닌 GitHub 릴리스로부터 플러그인 버전을 해석합니다.
로컬 소스 없이 복구 및 재배포. repo 권한을 가진 누구든 원본 작업 트리를 보유하지 않고도 알려진 릴리스를 다시 배포할 수 있습니다.
감사 추적. 어떤 소스가 언제 배포되었는지에 대한 시간 표시·태그 기록.

백엔드 vs GitHub

	백엔드	GitHub 아카이브
역할	Synapse 에이전트를 위한 런타임 레지스트리	버전이 부여된 소스 아카이브
소비 주체	실행 시점의 에이전트	`publish -m`, `package -m`, 소스를 열람하는 사용자
기록 시점	정식 `synapse plugin publish` 호출마다	동일 호출의 배포 후 단계 (GitHub 설정 시)
실패 영향	배포를 차단함 (반드시 성공해야 함)	경고만 기록 — 백엔드 배포는 그대로 성공

한쪽의 실패가 다른 쪽을 차단하지 않습니다.

사전 요구 사항

GitHub 아카이빙을 설정하기 전에 다음을 준비하세요:

인증 완료 (synapse login)
repo 스코프를 가진 GitHub Personal Access Token 준비
GitHub 조직(organization) 이름 확인 (기본값: synapse-plugins)

개요

한눈에 보기

기능	명령 / 설정	설명
설정	`synapse plugin github-setup`	GitHub 토큰과 조직 구성
제거	`synapse plugin github-clear`	GitHub 설정 제거
자동 아카이빙	`synapse plugin publish`	정식 배포 시 자동으로 아카이빙
일괄 배포	`synapse plugin publish -m plugin.yaml`	GitHub에서 가져와 백엔드로 배포
환경 변수	`SYNAPSE_GITHUB_TOKEN`, `SYNAPSE_GITHUB_ORG`	설정 파일 값을 재정의

동작 방식

GitHub 아카이빙은 옵트인(opt-in) 이며 비차단(non-blocking) 방식입니다:

옵트인: GitHub 설정이 존재할 때만 활성화됩니다 (github-setup 완료 시).
비차단: GitHub 아카이빙이 실패해도 백엔드 배포는 그대로 성공합니다 — 오류가 아닌 경고를 받게 됩니다.
Debug 건너뜀: synapse plugin publish --debug 는 빠른 반복 작업을 위해 GitHub 아카이빙을 완전히 건너뜁니다.

설정

GitHub 연동 구성

대화형 설정을 실행합니다:

synapse plugin github-setup

다음 항목을 입력하라는 프롬프트가 표시됩니다:

GitHub personal access token — 리포지토리와 릴리스 생성을 위해 repo 스코프가 필요합니다.
GitHub 조직 — 플러그인 리포지토리가 생성될 위치 (기본값: synapse-plugins).

이 명령은 토큰을 저장하기 전에 GitHub API를 호출하여 토큰을 검증합니다.

값을 직접 제공할 수도 있습니다:

synapse plugin github-setup --token ghp_xxxxxxxxxxxx --org my-org

설정은 ~/.synapse/config.json 의 github 키 아래에 저장됩니다.

환경 변수

환경 변수가 설정 파일보다 우선합니다:

변수	설명
`SYNAPSE_GITHUB_TOKEN`	GitHub personal access token
`SYNAPSE_GITHUB_ORG`	GitHub 조직 이름

# 환경 변수로 설정 (CI/CD에 유용)
export SYNAPSE_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export SYNAPSE_GITHUB_ORG=my-org

알아두면 좋은 점: 두 환경 변수가 모두 설정되어 있으면 설정 파일은 전혀 읽지 않습니다. 한쪽만 설정되어 있으면 나머지는 설정 파일에서 보충합니다.

설정 제거

# 대화형 확인
synapse plugin github-clear

# 확인 건너뛰기
synapse plugin github-clear -y

자동 아카이빙 워크플로우

synapse plugin publish 를 (--debug 없이) 실행하면, 백엔드 업로드가 성공한 후 SDK가 다음 단계를 실행합니다:

아카이빙되는 대상

모든 플러그인 소스 파일 (.synapseignore 규칙으로 필터링됨)
100MB를 초과하는 파일은 자동으로 건너뜀
백엔드에 업로드된 동일한 ZIP이 GitHub 릴리스 자산으로 첨부됨

출력 예시

GitHub 아카이빙이 포함된 성공적인 배포 출력:

Using config: config.yaml
Plugin: my-plugin v1.2.0 (neural_net)
Archive: 15 files, 45.2 KB

✓ Published to Backend (release_id: 42)

╭─ GitHub ──────────────────────────────────────╮
│ GitHub archived!                               │
│                                                │
│ Repo: https://github.com/my-org/my-plugin      │
│ Tag: 1.2.0                                     │
│ Release: https://github.com/my-org/my-plugin/  │
│          releases/tag/1.2.0                     │
╰────────────────────────────────────────────────╯

GitHub 아카이빙이 실패하면 대신 다음과 같은 경고가 표시됩니다:

Warning: GitHub archiving failed: <error details>
The plugin was published to Backend successfully.
GitHub sync can be retried later.

변형(Variant) 브랜치 전략

플러그인은 특정 고객 또는 배포 환경을 위한 커스터마이징된 빌드인 변형(variant) 을 가질 수 있습니다. 각 변형은 자체 브랜치와 태그 체계를 사용합니다.

브랜치 규칙

변형	브랜치	예시
없음 (기본)	`main`	`main`
`lig`	`variant/lig`	`variant/lig`
`ke`	`variant/ke`	`variant/ke`

태그 규칙

변형	태그 형식	예시
없음	`{version}`	`1.2.0`
`lig`	`{version}+{variant}`	`1.2.0+lig`
`ke`	`{version}+{variant}`	`1.2.0+ke`

+ 기호는 SemVer 빌드 메타데이터 규칙을 따릅니다.

리포지토리 구조

여러 변형을 가진 플러그인은 GitHub에 다음과 같은 구조를 만듭니다:

github.com/{org}/{plugin-code}/
├── main branch
│   └── tags: 1.0.0, 1.1.0, 1.2.0
├── variant/lig branch
│   └── tags: 1.0.0+lig, 1.1.0+lig
└── variant/ke branch
    └── tags: 1.0.0+ke

플러그인의 config.yaml 에서 변형을 지정하세요:

code: my-plugin
version: "1.2.0"
variant: lig  # 선택사항 — 기본 변형이라면 생략

매니페스트 기반 일괄 배포

여러 플러그인을 한 번에 배포하려면 플러그인 매니페스트(plugin.yaml)를 사용합니다.

plugin.yaml 작성

plugins:
  yolo_test:
    version: ">=2.0.0"
  sam2-smart-tool:
    version: ">=1.0.0"

각 항목은 플러그인 코드와 PEP 440 버전 지정자를 명시합니다. SDK는 GitHub 릴리스에서 가장 적합한 버전을 해석합니다.

축약형 (최신 버전):

plugins:
  yolo_test:
  sam2-smart-tool:

일괄 배포

# GitHub에서 해석 → 다운로드 → 백엔드로 배포
synapse plugin publish -m plugin.yaml

# Debug 모드 (백엔드 검증 건너뜀)
synapse plugin publish -m plugin.yaml --debug

추이 의존성 해석

플러그인이 config.yaml 에 dependencies 를 선언하면, 해당 의존성은 자동으로 해석되어 포함됩니다:

plugin.yaml: [sam2-smart-tool]       (1 declared)
  ↓ resolve + download
sam2-smart-tool
  → dependencies: { segment-anything-2: ">=2.0.0" }
    ↓ auto-added
segment-anything-2                    (2 total processed)

SDK는 추이 의존성을 처리하기 위해 사이클 감지가 포함된 BFS(너비 우선 탐색)를 사용합니다.

일괄 패키징

오프라인 배포를 위해 플러그인을 패키징할 수도 있습니다:

# 표준 패키징 (코드만)
synapse plugin package -m plugin.yaml

# 오프라인 패키징 (코드 + Python 휠)
synapse plugin package -m plugin.yaml --offline

안전 기능

원격 저장소 불일치 경고

아카이빙 전에 SDK는 플러그인 디렉토리에 로컬 .git/config 가 있고 remote origin URL이 설정되어 있는지 확인합니다. 그 URL이 아카이빙 대상과 다른 {org}/{repo} 를 가리키면 경고가 표시됩니다:

Warning: local git remote (personal-org/my-plugin) does not match
         archive target (datamaker-kr/my-plugin)

이는 서로 다른 조직에 중복 리포지토리를 실수로 만드는 일을 방지합니다.

사전 점검: 조직 접근 권한 검증

매니페스트 기반 일괄 작업(publish -m, package -m)에서는 SDK가 플러그인을 처리하기 전에 GitHub 토큰 권한을 검증합니다:

GET /orgs/{org} 를 호출하여 토큰 접근 권한 확인
토큰에 조직 권한이 없으면 조기에 실패
일괄 작업에서 부분 실패를 방지

치명적 오류 시 조기 종료

일괄 배포/패키징 중 치명적 오류(HTTP 401 Unauthorized 또는 403 Forbidden)가 발생하면, SDK는 남은 플러그인 처리를 계속하지 않고 즉시 중단합니다 — 동일한 인증 오류로 이후 작업도 모두 실패할 것이기 때문입니다.

문제 해결

문제	원인	해결책
"GitHub not configured"	토큰/조직이 저장되어 있지 않음	`synapse plugin github-setup` 실행
"Invalid GitHub token"	토큰이 만료되었거나 스코프가 잘못됨	`repo` 스코프를 가진 새 PAT 생성
조직 접근 시 404	토큰에 조직 권한이 없음	GitHub 설정에서 토큰을 해당 조직에 인가
"No files to archive"	`.synapseignore` 가 모든 파일을 제외함	`.synapseignore` 규칙 확인
원격 저장소 불일치 경고	로컬 git 원격이 아카이빙 대상과 다름	`github-setup` 에서 올바른 조직 확인
GitHub archive failed	네트워크 문제 또는 API 속도 제한	백엔드 배포는 그대로 성공; 나중에 재시도
일괄 배포 부분 실패	인증/네트워크 오류 혼재	요약 출력에서 플러그인별 상태 확인

플러그인 라이프사이클 컨텍스트​

아카이브가 별도 단계인 이유​

백엔드 vs GitHub​

개요​

한눈에 보기​

동작 방식​

설정​

GitHub 연동 구성​

환경 변수​

설정 제거​

자동 아카이빙 워크플로우​

아카이빙되는 대상​

출력 예시​

변형(Variant) 브랜치 전략​

브랜치 규칙​

태그 규칙​

리포지토리 구조​

매니페스트 기반 일괄 배포​

plugin.yaml 작성​

일괄 배포​

추이 의존성 해석​

일괄 패키징​

안전 기능​

원격 저장소 불일치 경고​

사전 점검: 조직 접근 권한 검증​

치명적 오류 시 조기 종료​

문제 해결​

관련 문서​