Gito

Gito는 agent-driven development를 위한 platformless Git control plane이다. 여러 Git platform의 공통 인터페이스를 제공해 repository registry, workspace lease, Git operation, provider adapter, normalized event를 하나의 제어 흐름으로 묶는다. Agent interaction UI는 sibling ../agent-shell Flutter package를 사용하고, 그 UI를 구동하는 backend/runtime은 sibling ../iop 프로젝트가 맡는 방향으로 둔다.

Git 자체 작업은 GitHub/GitLab/Gitea 같은 플랫폼을 몰라도 동작해야 한다. PR/MR, review, checks, webhook 같은 플랫폼 기능은 provider adapter 뒤에 둔다. 외부 연동은 GitHub webhook과 유사한 HTTP webhook/callback 모델을 기본으로 하고, Gito 전용 binary transport를 요구하지 않는다.

현재 상태

초기 scaffold 단계다. Go core는 build/test 가능한 최소 골격을 갖고 있고, Flutter client는 control surface 경계만 잡혀 있다.

현재 가능한 범위:

• Go server, worker command build
• health/readiness REST placeholder
• 내부 proto-socket registry와 binary event.subscribe / branch.updated event path
• Forgejo push callback, watched branch listener, branch event smoke/debug surface
• PostgreSQL-backed repo, workspace lease, operation, event, branch watch, revision cursor, provider delivery baseline
• platformless gitengine 최소 테스트
• core domain DTO 후보
• provider-neutral ChangeRequest adapter 경계
• Postgres migration 초기안
• agent-ops 규칙/스킬 기반 작업 진입점

아직 구현 전인 범위:

• event 외 내부 proto-socket channel/action의 실제 command behavior
• agent_shell: path: ../agent-shell package를 쓰는 Flutter host integration
• ../iop backend/runtime 결과를 Gito operation/event 계약으로 수렴시키는 연결
• 외부 consumer용 HTTP webhook delivery registration과 retry/outbox dispatch
• GitHub/GitLab/Gitea provider adapter와 Forgejo PR/MR adapter
• Flutter 화면 구성과 operation event 구독

빠른 시작

bin/test
bin/lint
bin/build

빌드가 끝나면 root bin/ 아래에 아래 실행 파일이 생성된다.

bin/gito-server
bin/gito-worker

서버 scaffold 실행:

HTTP_ADDR=:8080 bin/gito-server

확인:

curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz

주요 명령

목적	명령	비고
전체 테스트	bin/test	Go test 실행, Flutter test scaffold가 없으면 client test는 skip
lint	bin/lint	go vet ./..., Flutter가 있으면 flutter analyze --no-fatal-infos
build	bin/build	gito-server, gito-worker 생성
Core test	cd services/core && go test ./...	Go module 기준 직접 실행
Core lint	cd services/core && go vet ./...	Go vet 직접 실행

구조

경로	역할
services/core/cmd/server/	control plane server entrypoint
services/core/cmd/worker/	operation worker entrypoint
services/core/internal/controlplane/	REST API/webhook surface, internal proto-socket surface, auth/policy gate 후보
services/core/internal/core/	provider-neutral domain model
services/core/internal/gitengine/	platformless Git operation layer
services/core/internal/worker/	operation 실행 orchestration 후보
services/core/internal/provider/	GitHub/GitLab/Gitea/Plane/Jira adapter boundary
services/core/internal/events/	normalized event model
services/core/internal/storage/	PostgreSQL store boundary
services/core/migrations/	database schema migration
apps/client/	Flutter control surface scaffold
packages/contracts/	HTTP webhook/REST, internal proto-socket, event, DTO contract notes
docs/	사람용 architecture/operation 문서
agent-ops/	agent rules, skills, roadmap helper
agent-test/	local validation rules

설계 방향

Gito는 처음에는 modular monolith로 시작하되, 실행 역할은 분리 가능하게 둔다.

Flutter UI / gitoctl
        |
Control Plane
        |
Core Domain
        |
Worker / Scheduler
        |
IOP backend/runtime + Git Engine
        |
Provider Adapters

원칙:

• controlplane은 요청, 정책, 관찰, event stream을 소유한다.
• core는 repo, workspace lease, operation, revision cursor, event 원장을 소유한다.
• worker는 operation 실행과 외부 runtime 결과 수렴을 조율한다.
• Flutter host는 agent_shell: path: ../agent-shell dependency로 agent interaction UI/domain package를 붙인다.
• ../agent-shell은 Flutter agent UI/package이며 Gito backend가 아니다.
• ../iop는 agent backend/runtime을 맡고, Gito는 그 결과를 Git operation과 event 원장으로 수렴한다.
• gitengine은 platformless여야 하며 local bare repo만으로 테스트 가능해야 한다.
• provider는 PR/MR/review/checks/webhook 같은 플랫폼 기능만 맡는다.
• 외부 시스템은 GitHub webhook과 비슷한 HTTP webhook/callback으로 연결한다.
• proto-socket은 내부 control/runtime surface로만 사용하고, 외부 연결 규약이나 보조 transport로 제공하지 않는다.
• PostgreSQL은 source of truth이고, Redis는 필요할 때 fanout/stream 가속 계층으로만 둔다.

통신 정책

• 외부 provider와 consumer 연동은 REST API와 HTTP webhook/callback을 사용한다.
• proto-socket은 내부 control/runtime 통신에만 사용한다.
• REST는 health/readiness, provider callback, external webhook delivery, smoke/curl, 단순 bootstrap에 둔다.
• gRPC는 초기 설계에서 제외한다.
• webhook은 빠른 wakeup signal로만 보고, 최종 판정은 Git revision/diff 또는 provider read API로 재검증한다.

작업 맥락

작업을 시작할 때는 먼저 AGENTS.md를 읽고, 변경 경로에 맞는 domain rule을 확인한다.

주요 문서:

• Project rules
• Core domain rules
• Client domain rules
• Contracts domain rules
• Workspace ops rules
• Local test rules
• Architecture
• Control plane contract candidates

개발 흐름

1. 변경 전에 관련 domain rule을 읽는다.
2. core 변경은 cd services/core && go test ./... 또는 bin/test로 확인한다.
3. contracts 변경은 README/notes의 transport 정책과 맞는지 확인한다.
4. client 변경은 Flutter toolchain이 있으면 flutter analyze --no-fatal-infos와 flutter test를 실행한다.
5. 생성된 binary, .dart_tool/, local secret 파일은 commit하지 않는다.

환경 변수

이름	설명	필수
APP_ENV	runtime 환경 이름, 기본값 local	아니오
HTTP_ADDR	server listen address, 기본값 :8080	아니오
DATABASE_URL	PostgreSQL connection string, 없으면 in-memory runtime 사용	아니오
REDIS_URL	optional Redis endpoint	아니오
PROTO_SOCKET_PATH	proto-socket endpoint path, 기본값 /proto-socket	아니오
FORGEJO_WEBHOOK_SECRET	Forgejo push callback HMAC-SHA256 서명 키, 없으면 검증 생략	아니오
WORKER_ENABLED	worker 실행 여부, 기본값 true	아니오

Credential 값은 tracked 파일에 쓰지 않는다. 필요한 경우 credential_ref나 ignored local secret file로 연결한다.

참고 문서

• docs/architecture.md
• packages/contracts/notes/gito-control-plane.md
• agent-ops/skills/common/create-readme/SKILL.md