Git 통합 개요
Git 저장소를 Archyl에 연결하면 AI 기반 아키텍처 디스커버리가 활성화되어 문서를 실제 코드와 동기화할 수 있습니다.
지원되는 프로바이더
Archyl은 모든 주요 Git 호스팅 플랫폼을 지원합니다:
클라우드 프로바이더
| 프로바이더 | OAuth | 기능 |
|---|---|---|
| GitHub | 예 | 전체 지원 |
| GitLab | 예 | 전체 지원 |
| Bitbucket | 예 | 전체 지원 |
자체 호스팅
| 프로바이더 | 인증 방식 | 기능 |
|---|---|---|
| GitHub Enterprise | 토큰 | 전체 지원 |
| GitLab 자체 관리 | 토큰 | 전체 지원 |
| Gitea | 토큰 | 전체 지원 |
| Azure DevOps | 토큰 | 전체 지원 |
저장소 연결
1단계: 프로젝트 설정으로 이동
- 프로젝트를 엽니다
- 설정을 클릭합니다
- "저장소" 탭으로 이동합니다
2단계: 프로바이더 선택
- "저장소 연결"을 클릭합니다
- Git 프로바이더를 선택합니다
- Archyl을 인증합니다 (OAuth 프로바이더의 경우)
3단계: 저장소 선택
- 사용 가능한 저장소를 탐색합니다
- 연결할 저장소를 선택합니다
- 기본 브랜치를 선택합니다
- "연결"을 클릭합니다
인증
OAuth (권장)
GitHub, GitLab, Bitbucket 클라우드의 경우:
- "[프로바이더]로 연결"을 클릭합니다
- 팝업에서 Archyl을 인증합니다
- 접근 권한을 부여할 저장소를 선택합니다
OAuth 토큰은 안전하게 저장되며 자동으로 갱신됩니다.
개인 접근 토큰
자체 호스팅 또는 엔터프라이즈 프로바이더의 경우:
- Git 프로바이더에서 토큰을 생성합니다
- 필요한 범위:
repo(읽기 권한) - Archyl에 토큰을 입력합니다
저장소 접근
Archyl이 읽는 내용
AI 디스커버리 중 Archyl은 다음을 읽습니다:
- 파일 구조 및 이름
- 소스 코드 내용
- 설정 파일 (package.json, go.mod 등)
- README 파일
Archyl이 절대 접근하지 않는 내용
- 환경 파일 (.env)
- 자격 증명 또는 시크릿
- Git 이력
- 다른 브랜치 (명시적으로 선택하지 않는 한)
다중 저장소
여러 저장소를 단일 프로젝트에 연결:
모노레포
모노레포의 경우 한 번 연결하고 경로를 지정합니다:
/services/api
/services/web
/packages/shared
멀티레포
별도의 저장소의 경우:
- 각 저장소를 연결합니다
- 시스템 또는 컨테이너에 매핑합니다
- 모든 저장소에서 디스커버리가 실행됩니다
Webhook (곧 출시)
푸시 시 자동 동기화:
- 코드 변경 시 디스커버리 트리거
- 아키텍처 자동 업데이트
- 문서를 최신 상태로 유지
문제 해결
인증 실패
- 토큰에 필요한 권한이 있는지 확인하세요
- OAuth 앱이 인증되었는지 확인하세요
- 재연결을 시도하세요
저장소를 찾을 수 없음
- 저장소에 대한 접근 권한이 있는지 확인하세요
- 저장소 URL을 확인하세요
- 브랜치가 존재하는지 확인하세요
디스커버리 오류
- 제외 경로를 확인하세요
- 동시성 설정을 줄이세요
- AI 프로바이더 제한을 검토하세요