gitai로 AI 에이전트 친화적인 버전 관리 서버 구축하기

gitai란 무엇인가요?

gitai는 AI 코딩 에이전트를 위해 설계된 오픈 소스 버전 관리 시스템입니다. 클라이언트가 온라인 상태를 유지하면서 필요한 객체와 경로만 가져오고, 소스 제어 작업을 서버로 보내는 서버 중심 접근 방식을 구현합니다.

이 프로젝트는 Anthropic의 Scion에 대해 공개적으로 설명된 설계에서 영감을 받았지만, gitai는 독립적으로 구현되었습니다. MIT 라이선스를 따르며 특정 공급업체에 종속되지 않고, 서버가 언어 모델을 호출할 필요도 없습니다. AI 기반 작업은 어떤 공급업체든, 결정론적 도구든, AI 공급자 없이도 사용할 수 있습니다.

gitai는 내부적으로 일반 Git 저장소를 사용하면서 기록 조회, 반영, 변경 세트 추적, 저장소 조정을 서버로 이전합니다. 이 모델은 공유 브랜치에 변경 사항을 빠르게 반영해야 하는 수명이 짧은 작업이 많은 워크로드를 위한 것입니다.

주요 기능

• 선택적 데이터 액세스: 객체 서비스는 개별 객체와 희소 트리를 제공합니다. graft clone 및 graft sparse 명령은 요청된 경로만 구체화합니다.
• 서버 측 기록: blame, 경로 기록, 조상 관계, 코드 검색은 서버에서 실행되며 파생 데이터로 메모이제이션됩니다.
• 동시 반영: UserLand는 변경 사항을 현재 브랜치 끝에 리베이스하고 기존 병합 큐 대신 비교 후 교환 업데이트를 사용합니다. 동시에 반영된 변경 사항은 하나의 참조 업데이트로 일괄 처리할 수 있습니다.
• 충돌 해결: 충돌하는 반영 작업은 버전이 지정된 공급업체 중립 프로토콜을 통해 선택한 해결 프로그램을 사용할 수 있습니다.
• 변경 세트 로그: 수락된 참조 업데이트는 작업과 수행자를 순서가 지정된 로그에 기록하며, 클라이언트는 이를 조회하거나 감시할 수 있습니다.
• 확장 가능한 저장소: SQLite 또는 PostgreSQL은 변경 세트, 참조, 리뷰, 미리 쓰기 로그를 저장하고, 콘텐츠 주소 지정 팩은 파일 저장소, S3, GCS 또는 Azure에 저장할 수 있습니다.
• 에이전트 제어: 에이전트별 토큰, RPC 허용 목록, 브랜치 정책에 따라 에이전트가 수행할 수 있는 작업이 결정됩니다.
• 검증 및 모니터링: graft-verify는 끝점을 테스트하고, 실패를 이분 탐색하며, 원인이 된 변경 사항을 되돌릴 수 있습니다. 슈퍼팬이라고 하는 모니터링 에이전트는 변경 세트 스트림을 추적하고 Slack을 통해 보고할 수 있습니다.
• 엄격한 캐싱: graft-cache는 데몬 및 리전 계층에 변경 불가능한 객체를 캐시하면서 각 객체를 검증할 수 있습니다.

아키텍처 작동 방식

에이전트, CI 작업, 희소 작업 공간은 Graft CLI 또는 gRPC를 통한 Go SDK를 사용해 gitai 서버와 통신합니다. 선택 사항인 graft-cache 데몬을 서버 앞에 배치하여 추가 캐시 계층을 제공할 수 있습니다.

서버는 반영, 객체 액세스, 변경 세트, 파생 데이터, 검색, 리뷰를 처리합니다. 서버의 쓰기 경로는 각 참조에 대한 변경 세트와 비교 후 교환 작업을 결합합니다. 데이터베이스 저장소에는 변경 세트 미리 쓰기 로그, 참조, 변경 로그, 리뷰가 저장됩니다. 객체 저장소에는 콘텐츠 주소 지정 팩이 저장됩니다.

서버 노드는 재구축할 수 있는 상태 비저장 캐시로 설계되었습니다. 따라서 배포 규모가 커지면 노드를 추가할 수 있습니다. 로컬 Git 저장소는 어느 노드에서든 재구축할 수 있는 캐시로 계속 사용할 수 있습니다.

자세한 내용은 프로젝트의 아키텍처 문서 및 저장소 문서를 참조하세요.

gitai 설치 및 빌드

1. 사전 요구 사항 설치

gitai에는 현재 Linux 또는 macOS, Go 1.26, C 도구 체인, Meson, Ninja가 필요합니다. 빌드 과정에서 Git 번들 버전을 컴파일하므로 시작하기 전에 필요한 네이티브 빌드 도구를 사용할 수 있는지 확인하세요.

2. 저장소 복제

git clone https://github.com/feder-cr/git-ai.git
cd git-ai

3. 바이너리 빌드

Make 대상을 실행하여 서버, CLI 및 지원 도구를 빌드하세요.

make build

생성된 바이너리는 _build/bin에 배치됩니다. CLI와 사용 가능한 명령을 확인하려면 다음을 실행하세요.

./_build/bin/graft

빠른 시작 실행

저장소에는 서버, 캐시 데몬, 두 개의 에이전트, 반영 작업으로 구성된 임시 gitai 환경을 시작하는 예제가 포함되어 있습니다.

examples/graft/quickstart.sh

영구 데이터베이스, 객체 저장소 또는 배포를 준비하지 않고 핵심 워크플로를 확인하는 가장 빠른 방법입니다. 이 예제는 임시 디렉터리를 사용하므로 학습과 실험에 적합합니다.

자체 서버 실행

1. 예제 구성으로 시작

사용자 지정 서버 구성의 시작점으로 examples/graft/config.toml을 사용하세요. 빌드된 바이너리로 서버를 시작할 수 있습니다.

_build/bin/gitaly serve config.toml

소스 트리에서 서버 측 확장 기능은 Graft라고 합니다. [graft] 구성 섹션, graft CLI, internal/graft 패키지, Graft 문서에서 이 이름을 확인할 수 있습니다.

2. 데이터베이스 및 객체 저장소 추가

저장소 상태를 데이터베이스와 객체 저장소에 저장하는 배포에서는 구성에 [graft.storage] 섹션을 추가하세요. 문서화된 마이그레이션 절차는 shadow 모드로 시작하여 저장소를 가져온 다음 authoritative 모드로 전환하는 것입니다.

정확한 구성 및 마이그레이션 세부 정보는 저장소 가이드를 참조하세요. 지원되는 저장소 모델은 조정 데이터에 SQLite 또는 PostgreSQL을 사용하고, 콘텐츠 주소 지정 팩에 파일, S3, GCS 또는 Azure 저장소를 사용합니다.

에이전트 변경 사항 작업

전통적인 Git 워크플로에서는 각 작업자가 저장소를 복제하고, 로컬에서 개발한 다음, 공유 브랜치에 푸시할 수 있습니다. 반면 gitai를 사용하면 에이전트가 서버에 연결된 상태를 유지하면서 필요한 데이터만 요청할 수 있습니다.

에이전트는 희소 작업 공간을 사용해 실제로 생성되는 경로를 제한할 수 있습니다. 관련 명령은 다음과 같습니다.

• graft clone은 저장소에서 선택한 뷰를 실제 작업 공간에 생성합니다.
• graft sparse는 작업에 필요한 경로만 요청하거나 조정합니다.

에이전트가 기여할 준비가 되면 UserLand는 변경 사항을 현재 팁 위로 리베이스하고 비교 후 교환(compare-and-swap) 업데이트를 시도합니다. 여러 에이전트가 한 브랜치에 동시에 변경 사항을 반영하는 경우, gitai는 각 에이전트가 별도의 병합 대기열을 거치도록 하는 대신 이러한 작업을 하나의 참조 업데이트로 일괄 처리할 수 있습니다.

반영 과정에서 충돌이 발생하면 충돌 해결 문서에 따라 해결 프로그램을 구성하세요. 해결 프로그램은 LLM 제공자, 결정론적 도구 또는 외부 AI 제공자를 사용하지 않는 방식으로 구성할 수 있습니다.

변경 세트, 리뷰 및 검증 살펴보기

변경 세트 기록

수락된 모든 참조 업데이트는 변경 세트 로그의 항목이 됩니다. 항목에는 작업과 수행자가 포함되므로, 클라이언트는 순서가 지정된 기록을 조회하거나 실시간으로 감시할 수 있습니다. 이 스트림은 특정 구성 요소와 관련된 변경 사항을 추적하는 모니터링 에이전트의 구동에도 사용할 수 있습니다.

리뷰 및 정책

gitai에는 의미 기반 승인 규칙을 사용하는 에이전트 친화적인 리뷰 기능이 포함되어 있습니다. 예를 들어 주석만 변경하는 작업에는 로직 변경보다 적은 수의 승인을 요구할 수 있습니다. 에이전트 보안 제어에는 에이전트별 토큰, RPC 허용 목록 및 브랜치 정책도 포함됩니다.

서버를 자동화된 사용자에게 공개하기 전에 리뷰 문서와 에이전트 보안 문서를 읽으세요.

반영 후 검증

graft-verify 워크플로는 변경 사항이 반영된 후 브랜치 팁을 테스트합니다. 테스트가 실패하면 변경 사항을 이분 탐색하고 실패를 유발한 변경 사항을 되돌릴 수 있습니다. 이를 통해 통합이 지속적으로 이루어지고, 시스템이 손상된 팁의 원인이 된 변경 사항을 식별하는 워크플로를 지원합니다.

지원되는 워크플로와 구성은 검증 가이드를 참조하세요.

고급 배포 팁

• 캐싱을 신중하게 사용하세요: 에이전트나 CI 작업이 데몬 또는 리전별 캐시 계층 전반에서 변경할 수 없는 객체에 빠르게 액세스해야 한다면 graft-cache를 추가하세요.
• 조정과 객체 저장소를 분리하세요: 변경 세트와 참조에는 SQLite 또는 PostgreSQL을 사용하고, 저장소 팩에는 객체 저장소 백엔드를 구성하세요.
• 노드를 추가해 확장하세요: 서버 노드는 재구축 가능한 캐시로 설계되었으므로, 노드를 추가할 때 각 노드가 독립적인 권위 상태를 보유하도록 할 필요가 없습니다.
• 반영 문서를 읽으세요: 반영 및 일괄 처리 가이드에서는 비교 후 교환 워크플로와 동시 업데이트를 설명합니다.
• 현재 제한 사항을 검토하세요: 이 버전은 0.1.0이며 1.0 이전에는 인터페이스가 변경될 수 있습니다. 팩의 가비지 컬렉션과 같은 알려진 미비점은 LIMITATIONS.md에 문서화되어 있습니다.
• 설계 문서를 활용하세요: PLAN.md부터 PLAN6.md까지의 문서에서 구현의 근거와 발전 과정을 설명합니다.

결론

gitai는 여러 코딩 에이전트가 동시에 작업하는 저장소에 서버 중심 소스 제어 모델을 적용합니다. Graft CLI와 서버는 희소 데이터 액세스, 서버 측 기록, 비교 후 교환 방식의 반영, 충돌 해결, 변경 세트 로그, 리뷰, 검증 및 확장 가능한 저장소를 제공합니다.

make build와 examples/graft/quickstart.sh로 시작한 다음, 워크플로를 이해하면 구성된 서버와 영구 저장소로 전환하세요. 구현 및 운영에 관한 자세한 지침은 프로젝트의 Quickstart, 구성 참조 문서 및 아키텍처 문서를 활용하세요.