Add a repository
Add a local repository or a GitLab project, and the rules for names and prefixes.
Before the control plane can plan anything, it needs your code. Add the Git repository that has your OpenTofu stacks, and the control plane reads it by commit and finds the stacks in it.
You can add a local repository to writ serve --dev, or a GitLab project to a team's writ serve. To learn how the control plane reads and polls a repository, see Repositories.
Before you begin
- On a team's control plane, you need
adminon every stack in every environment. See Rules for adding a repository. - You need
gitonPATHfor bothwritandwrit serve --dev. The Nix package brings it. The release binary doesn't, and the container image, which is for a team'swrit serve, has none, as Install: Git explains.
Add a local repository to writ serve --dev
In the repository, run writ repo add .. It adds the Git repository that contains the current directory. The path is that directory, from the top of its Git work tree, and the name is the directory's name.
Here's a new repository whose one stack is app:
$ writ repo add .
Repository demo: /home/alice/demo, path the root, branch main.
Read main at 42bf997f from the local repository: 1 file, 1 stack.
STACK SERVED
app dev
Next: in a clean work tree of it, writ plan --remote plans the commit you are on.Output of a real run, 2026-11-16.
Your work tree is never read. The dev control plane reads the repository's commits with the git binary. Git runs with no hook, no core.fsmonitor program, no system or global config, no GIT_ variable from the environment of writ serve --dev, no replacement objects, and no transport. So if your repository's config asks for a fetch, that fetch fails.
Unlike the plan tool of writ mcp, the dev control plane follows .git/objects/info/alternates, .git/commondir, and a .git file, because it reads a repository a person added.
Because git reads no global config, it doesn't read a safe.directory there. So the repository must belong to the user that runs writ serve --dev.
Add a GitLab project
To add a project, run writ repo add NAME FORGE/PROJECT. For FORGE, give a forge's name in the config or its host. Use --path to set the directory under which the control plane finds stacks.
The control plane resolves the path to the project's numeric id, reads the default branch's head, lists its files, and finds the stacks. You'll see the same lines as for a local repository, with the Git host, the project, and its id in place of the local path. It says that it read the commit with the forge's read-only token, and suggests writ ci gitlab --repo NAME as the next step.
There's no output here yet. Only the tests' stand-in of GitLab has served one, and the test plan for a real project hasn't run.
Add one from the control UI
If you prefer the browser, open Repositories at /ui/repos. It lists each repository with its last commit read and its last poll.
Add repository, at /ui/repos/new, is a form with the same fields, sent to POST /v1/repos by the server in process. It takes no token. If Writ refuses the form, it comes back with the refusal and what you typed.
After you add one, the repository's page at /ui/repos/NAME shows the stacks found. Getting started, at /ui/start, lists what the control plane has and your next step. Under writ serve --dev, the start banner prints a sign-in link that works once, for 10 minutes, and writ ui prints another.
Rules for adding a repository
To add a repository, you need admin on every stack in every environment, because its code can contain any stack. That's why most teams pin their repositories with repo blocks instead, where the config's review covers them. On writ serve --dev, the dev team can add any repository.
Which grants count. Only grants with envs = ["*"] count, and their stacks must match every stack name of every depth up to 64 parts, the most a 128-character name can have. A pattern of * parts alone covers names of exactly that many parts ("*", "*/*", and so on). If you mix * and ** parts, the pattern covers names of at least as many parts as its * parts, so stacks = ["**"] covers every depth on its own.
Names and projects are unique. You can't add a second repository with the same name, or the same project and path.
Stack names are unique too. Writ keeps state by stack name, so each stack name is unique on a control plane. If your repository has a stack whose name another repository has, Writ refuses it, and the message suggests a prefix. With --prefix payments/, its stacks are named payments/network and so on.
Prefixes can't overlap. A prefix can't start with another repository's prefix, or be the start of one: payments/ and payments/eu/ are refused together, and the message says which repository has the other. Two repositories can have the same prefix, and one can have none. The pinned list in your config follows this rule too: if a repository breaks it, it isn't added, and the control plane logs why.
Stack names can't start with another prefix. That's true in either repository. So an unprefixed repository with the stack a/x is refused next to a repository with the prefix a/, and the reverse, and the message lists both repositories.
The poll applies this rule to later commits. If a commit adds such a stack, or one whose name another repository's stack has, Writ doesn't record it. The repository's head stays where it was, and its error says why until a commit fixes it.
Writ checks a repository against the others inside the transaction that stores it, so two requests at once can't both pass.
Pin the list in your config. When your config has repo blocks, they pin the list. Writ then refuses POST /v1/repos, and the poll adds, replaces, and removes rows to match the config:
repo {
name = "infra"
forge = "gitlab"
project = "acme/infra"
path = "infra"
}Next steps
- Set up GitLab CI:
writ ci gitlab --repo NAMEprints the jobs to include. - Repository routes: the API behind
writ repo add.
This page is built from docs/add-repository.md in the repository. It is also served as plain Markdown.