Git designed for AI agents.
Graft quickstart
This walks through a single-machine setup: one standalone Gitaly, two agents
with different policy rules, a graft-cache daemon in front of it, and the
graft CLI as an agent workspace. It takes about ten minutes by hand.
For requests made with an agent token, the policy decides on the agent of the token, so one agent cannot act as the other. Read LIMITATIONS.md, Security limitations, before you give tokens to anything you do not control.
examples/graft/quickstart.sh runs the
same steps non-interactively, under one work directory, and is the fastest way
to see Graft work. The steps below explain what the script does.
1. Build the binaries
From a checkout of this repository, with the Gitaly build dependencies installed (see "Installation" in the Gitaly part of the README):
make build
mkdir -p /var/lib/graft/bin
cp _build/bin/gitaly _build/bin/gitaly-hooks _build/bin/gitaly-ssh /var/lib/graft/bin/
cp _build/bin/graft _build/bin/graft-cache /usr/local/bin/
make build compiles the bundled Git and embeds it, with gitaly-hooks and
gitaly-ssh, into the gitaly binary. A plain go build ./cmd/gitaly does not
build them and fails on a fresh checkout. The example configuration sets
bin_dir to /var/lib/graft/bin.
2. Create the configuration
mkdir -p /var/lib/graft/repos /var/lib/graft/run /etc/graft/tokens
cp examples/graft/config.toml /etc/graft/config.toml
The example defines two agents, planner and builder, a storage at
/var/lib/graft/repos, and a policy. planner may land on main. Everybody
else may not, and every branch is open to all callers. See
CONFIGURATION.md for every key.
Create the agent token files that the configuration references:
for agent in planner builder; do
openssl rand -hex 32 > "/etc/graft/tokens/$agent"
chmod 0600 "/etc/graft/tokens/$agent"
done
3. Start Gitaly in standalone mode
/var/lib/graft/bin/gitaly serve /etc/graft/config.toml
With [graft] standalone = true, Gitaly needs no GitLab URL or secret. Every
access check is answered from the policy.
4. Create a repository
Creating a repository is an operator action: it needs the shared token of the
[auth] section, and an agent token is refused. --initial-commit gives the
repository a first commit (a README.md) on its default branch, main,
because a clone needs an existing branch:
GRAFT_ADDRESS=unix:/var/lib/graft/run/gitaly.sock \
GRAFT_TOKEN=change-me-shared-token \
GRAFT_USER=planner \
GRAFT_AUTHOR="planner <[email protected]>" \
graft repo create demo.git --initial-commit --branch feature/demo
The initial commit passes the policy like any write, as the user of
GRAFT_USER: here planner, who may write main. --branch feature/demo
also creates feature/demo at the initial commit, which the builder lands on
below. The command converges on the state it asks for: if it fails part way,
run it again, and it does only what is left (graft repo create -h has the
rules).
5. Start the cache daemon
graft-cache sits between clients and Gitaly. Run one daemon per node:
graft-cache \
--listen unix:/var/lib/graft/run/cache.sock \
--upstream unix:/var/lib/graft/run/gitaly.sock \
--tier daemon \
--max-bytes 1073741824 \
--metrics-addr 127.0.0.1:9236
The daemon keeps objects in memory only. For a regional tier that also stores
objects on disk, run another graft-cache --tier cache --disk-dir /var/lib/graft/cache
whose --upstream is the Gitaly socket, and point the daemon's --upstream at
it. Tiers chain: a daemon may point at a cache tier, which points at Gitaly.
Clients connect to the daemon's socket. Gitaly's own socket is for the cache tier and administrative tools.
6. Clone and commit as the planner
The CLI reads its settings from the environment. Set GRAFT_USER to the agent
name of the token: it names the temporary branches of commits
(graft/<user>/...). With an agent token, the server uses the agent name as the
user ID of every request whatever GRAFT_USER says, and the policy decides on
the agent of the token. The user ID is used verbatim in the branch name when it
is a valid reference name component, so a policy can grant refs/heads/graft/<agent>/**
to each agent. Other names, such as names with spaces, become a lowercase slug
of letters, digits and dashes.
export GRAFT_ADDRESS=unix:/var/lib/graft/run/cache.sock
export GRAFT_STORAGE=default
export GRAFT_TOKEN="$(cat /etc/graft/tokens/planner)"
export GRAFT_USER=planner
export GRAFT_AUTHOR="planner <[email protected]>"
graft clone "$GRAFT_ADDRESS" demo.git ./demo --branch main
cd ./demo
printf 'hello graft\n' > README.md
graft commit -m "Add README" --land main
graft commit writes the commit on a temporary branch,
refs/heads/graft/<user>/<random>. --land main then lands it on main with
UserLand. Without --land, the commit stays on the temporary branch, and
graft land lands it later.
7. Land a feature as the builder
The builder may not write to main, but it may write to any other branch:
export GRAFT_TOKEN="$(cat /etc/graft/tokens/builder)"
export GRAFT_USER=builder
export GRAFT_AUTHOR="builder <[email protected]>"
printf 'feature\n' > feature.txt
graft commit -m "Add feature" --land feature/demo # allowed
printf 'nope\n' >> README.md
graft commit -m "Denied change" --land main # refused by the policy
The refusal names the rule that decided it, for example policy denies "builder" to update "refs/heads/main" (rule 2). The commit stays on the builder's
temporary branch, and the land is pending. graft land --abort drops the
pending commit and keeps the local changes. graft revert README.md takes the
server's version.
8. Read history and follow the log
graft status
graft log # changeset log: sequence, reference, OIDs, operation, actor, time
graft blame README.md # who last changed each line
graft history README.md # commits that changed the file
graft cat main:README.md # a file at a revision
graft watch # follow new changesets until interrupted
The log lists every reference update the server accepted, including the
temporary branches. A land appears as land next to the commit_files and
delete_branch entries of its temporary branch. Each entry names the actor.
9. Sparse workspaces
Materialize only part of a large tree:
graft sparse docs/ src/api/
graft update # moves the base to the branch tip; refuses if local changes touch updated files
10. Check the cache
With --metrics-addr set, the daemon serves its statistics as JSON:
curl -s http://127.0.0.1:9236/stats
object_hits grows when a read is served from memory. A second clone of the
same tip is a typical example.
Next steps
- ARCHITECTURE.md explains how the pieces interact.
- CONFIGURATION.md lists the
[graft]keys and the CLI settings. - LIMITATIONS.md lists what is not done yet.