Git designed for AI agents.
Graft architecture
Graft is a fork of Gitaly that turns it into a standalone, agent-scale, server-centric version control server. This document describes how the pieces fit together and maps each idea from Anthropic's description of its internal "Scion" system to the Graft component that implements it.
Everything described here is implemented. Items that are not implemented are marked "not yet" and are listed in LIMITATIONS.md.
Components at a glance
agents, CI jobs, sparse workspaces, scripts
+----------------------------------------------------------------+
| graft CLI (cmd/graft) Go SDK (sdk/) |
+--------------------------------+-------------------------------+
| gRPC (unix socket or TCP)
v
+----------------------------------------------------------------+
| graft-cache, daemon tier (cmd/graft-cache, --tier daemon) |
| - byte-bounded object LRU in memory |
| - coalesces concurrent misses, verifies object IDs |
+--------------------------------+-------------------------------+
| gRPC, one batched GetObjects per miss set
v
+----------------------------------------------------------------+
| graft-cache, cache tier (regional, optional, --tier cache) |
| - LRU plus optional on-disk store (--disk-dir) |
+--------------------------------+-------------------------------+
| gRPC, transparent proxy
v
+-----------------------------------------------------------------------------+
| gitaly ([graft] standalone = true, no GitLab) |
| |
| auth: per-agent tokens and the shared auth.token |
| requestdefaults: sets gl_id / gl_username from the token identity |
| |
| ObjectService ChangesetService DerivedDataService OperationService|
| GetObjects ListChangesets Blame UserLand |
| GetTree WatchChangesets PathHistory (and all others)|
| | | | | |
| v v v v |
| catfile cache changelog store derived store quarantine, |
| (object reads) graft/changesets graft/derived compare-and- |
| .jsonl (flock) content-addressed swap ref update|
| |
| standalone client: [[graft.policy]] answers the access checks that GitLab |
| would answer (update allowed, pre-receive, post-receive) |
+----------------------------------------+------------------------------------+
|
v
bare Git repositories (normal Git, on disk)
Every repository stays a normal Git repository. Anything that speaks upstream Gitaly RPCs keeps working. Graft adds RPCs, and it changes how access checks are answered when GitLab is absent.
Mapping of Scion ideas to Graft
The article describes a handful of ideas. The table lists each one and the Graft component that implements it.
| Scion idea (from the article) | What it means | Graft component | Where |
|---|---|---|---|
| Always-online clients | Clients keep no full clone; they ask the server for what they need, when they need it | ObjectService (GetObjects, GetTree), graft clone and graft sparse, the SDK |
proto/object.proto, internal/gitaly/service/object, cmd/graft, sdk |
| Fetch exactly what is needed | Sparse trees and single blobs instead of packfile negotiation | GetTree with recursive and include_sizes; GetObjects by OID, resumable after a dropped stream |
internal/gitaly/service/object |
| Source control as an API | History operations (blame, path history) run on the server | DerivedDataService (Blame, PathHistory) and the existing CommitService RPCs |
internal/gitaly/service/derived, internal/graft/derived |
| Landing without a merge queue | The server rebases or merges a change onto the current tip and retries when the tip moves | OperationService.UserLand with compare-and-swap retries (max_attempts, default 20) |
internal/gitaly/service/operations/land.go |
| Changeset log | Every accepted reference update is recorded in an ordered log with a dense sequence that clients can follow | ChangesetService (ListChangesets, WatchChangesets) over <git dir>/graft/changesets.jsonl |
internal/graft/changelog, internal/gitaly/service/changeset |
| Derived data computed once | Expensive answers (last commit that changed a path, blame) are memoized under immutable keys and reused | Content-addressed derived store keyed by SHA-256 of (kind, commit, path) | internal/graft/derived, internal/gitaly/service/derived |
| Strict cache tiers | Immutable objects are cached at several layers, and every stored object is verified | graft-cache in daemon and cache tiers; byte-bounded LRU, optional disk store, one batched upstream call per miss set |
cmd/graft-cache, internal/graft/cachetier |
| Access control without a central queue | Who may update which reference is decided by a local, ordered policy, per request | Standalone client evaluating [[graft.policy]]; the policy decision and the changeset actor use the agent of the token (see LIMITATIONS.md) |
internal/gitlab/standalone_client.go, internal/gitaly/server/auth |
| Automatic conflict resolution (phase 2) | A land that conflicts is resolved by a tool instead of bouncing back to the author | UserLand with resolve_conflicts calls an operator-chosen resolver over a versioned JSON protocol; graft-resolve ships deterministic strategies and an optional llm strategy outside the server (RESOLVE) |
internal/gitaly/service/operations/land_resolve.go, internal/graft/resolver, tools/graft-agents/resolve |
| Test after landing, revert the culprit (phase 2) | Changes land first; tests run on the tip afterwards, and a breaking change is found by bisection and reverted | graft-verify: green ref, bisection, UserRevert with a Graft-Auto-Revert trailer and a cap per hour (VERIFY) |
cmd/graft-verify, internal/graft/verify |
| Monitoring agents ("superfans", phase 2) | In the article, one agent per component reads its telemetry and logs to catch subtle problems. Graft's superfans follow the changeset stream instead (not the servers' telemetry) and report what matters to each component's owners | graft-superfan reads graft watch --json, applies deterministic rules and sends digests; an optional llm summarizer (SUPERFAN) |
tools/graft-agents/superfan, tools/graft-agents/notify |
| Access control for agents (phase 2) | The article mentions repository- and directory-level permissions; Graft gives agents the least authority that lets them land (directory-level permissions are not implemented) | Agent RPC allowlist, policy on every reference update including HEAD (AGENT-SECURITY) |
internal/gitaly/server/auth, internal/gitaly/hook/referencetransaction.go |
Data flows
Land (graft commit --land or UserLand)
client graft-cache (optional) gitaly (standalone)
| | |
| CommitFiles(start=base, | |
| branch=graft/<user>/<rand>) | pass-through |
|------------------------------->|----------------------------->| write commit C,
| | | update the temporary branch
| | |
| UserLand(branch=main, | |
| commit=C, strategy=rebase) | |
|------------------------------->|----------------------------->| 1. read the tip T of main
| | | 2. T is an ancestor of C: fast-forward
| | | C is reachable from T: already_landed
| | | C landed before as C', C' reachable
| | | from T: already_landed (PLAN11)
| | | otherwise rebase C onto T
| | | 3. update hooks and the standalone policy
| | | 4. compare-and-swap main from T to C'
| | | lost the race: retry from 1 (jittered)
| | | 5. changeset: operation=land, actor,
| | | rewritten=true when history changed,
| | | lands=[C -> C']
| UserLandResponse | |
|<-------------------------------|<-----------------------------|
| | |
| UserDeleteBranch(temporary) | pass-through |
|------------------------------->|----------------------------->| changeset: operation=delete_branch
The temporary branch is written with commit_files and removed with
delete_branch, so the changeset log shows both steps next to the land.
Read (sparse checkout and history)
client graft-cache daemon cache tier gitaly
| GetTree(rev, path, | | |
| recursive) | no tree_oid: forwarded | |
|------------------->|------------------------------------->|------------------->| tree listing
| | | |
| GetObjects(oids) | memory hit: stream from the cache | |
|------------------->| miss: all misses in ONE call --------|------------------->| catfile batch read
| | verify IDs, store, coalesce | |
| chunks in order | | |
|<-------------------| | |
| Blame(rev, path) | forwarded (derived data is not cached at this tier) |
|------------------->|------------------------------------->|------------------->| lastmod(commit, path)
| memoized in
| graft/derived;
| blame cached at
| the lastmod commit
Watch (changeset log)
client gitaly
| WatchChangesets(after_sequence=N) |
|----------------------------------------------->| stream the backlog: sequence > N, in order
|<-----------------------------------------------| ...
| | keep the stream open. A new changeset is
| | sent when the log is appended (in-process
| | broadcast) and by a re-read every second
|<-----------------------------------------------| new changesets, dense sequence
| cancel |
|----------------------------------------------->| end the stream
Consistency and failure model
- Reference updates go through Gitaly's normal transaction path, so hooks and the reference-transaction hook see every change. The changeset log is appended from that hook after the update is committed. A failure to record is logged and never fails the update.
- The changeset log is append-only and its sequence numbers are dense from 1.
Appends are serialized per repository with an in-process mutex and an
flockonchangesets.jsonl.lock, and are fsync'd. A torn last line after a crash is ignored and truncated on the next append. - Objects are immutable, so
GetObjectsresponses can be cached by OID. The cache recomputes the object ID of every object it stores from the object type, size and content, and refuses to serve or store an object that does not match. - Derived data is content-addressed and immutable. Entries are written atomically (temporary file and rename). A crash leaves at most a missing entry, which is recomputed on the next read.
Trust boundaries
- Clients authenticate with the shared
auth.tokenor with a per-agent token ([[graft.agent]]). The token gives the request an identity, the agent name. In standalone mode, requests made with an agent token always get that name as their acting user ID. Other requests get the identity name (sharedoranonymous) only when they carry no acting user ID. - The acting user ID is a value the client sends in
gitaly.User.gl_id. For a request made with an agent token, neither the policy nor the changeset actor uses it: both use the agent of the token, carried to the hooks in the hooks payload. For the shared token, the policy decides on the acting user ID. See LIMITATIONS.md under Security limitations. - In standalone mode there is no GitLab. The access policy in
[[graft.policy]]is the only authorization check for reference updates. Treat the policy file as security configuration. For agent tokens, the reference-transaction hook enforces it on every reference update. The pre-receive hook enforces it on pushes and OperationService RPCs for every caller. Agent tokens cannot call the administrative RPCs that bypass reference transactions, such asRemoveRepository,SetCustomHooksandHookService. See LIMITATIONS.md, "Which updates the policy covers". - The cache tier forwards the client's authorization metadata upstream when the
client sent one. Otherwise it uses its own
--token. Every cached read is first checked against the upstream with the caller's credentials. Access is therefore never wider than the token the caller presents, but a client that sends no authorization is served with the tier's token, and that widens access. With--tokenset, every client that can reach the tier without credentials gets the tier token's access. Without--token, such a client is refused. See the package documentation ofinternal/graft/cachetier.