Grounding drafts in your code repository

Link a code repository to a project and Workover AI can write technical drafts from the code, rather than from what sounds plausible. This page covers what grounding needs, how to set it up, and how to tell whether a draft was grounded.

Why it matters

An assistant writing about your API without seeing it produces something that reads correctly and is wrong in the details: the parameter that does not exist, the response shape from a different version, the endpoint that was renamed last quarter. Those errors are expensive precisely because the prose is fluent.

Grounded in the repository, a draft describes what the code does. It can still be wrong, but it is wrong in ways you can check against a file.

What grounding needs

Grounding works only when all three of these are true:

An AI provider that can read repositories, chosen under Settings > AI. See Choose who provides Workover AI and the provider table below.
A code host connected to the workspace: GitHub, GitLab or Bitbucket, under Settings > Integrations. For GitHub, see GitHub.
A repository linked to the project, under Project settings > Linked repositories. Connecting the host is not enough on its own.

Which providers can ground

Provider	Can ground drafts?	How the code is read
Anthropic (Claude)	Yes, on GitHub, GitLab and Bitbucket	On GitHub and GitLab, the model reads the repository on the host, and your source code does not pass through Workover. On Bitbucket, Workover reads the files the draft needs and passes them to the model.
GLM Coding Plan (Z.ai)	Yes, on GitHub and Bitbucket. Not on GitLab.	Workover reads the files the draft needs and passes them to the model.
OpenRouter	No	Drafts are written from the prompt only.
OpenAI	No	Drafts are written from the prompt only.

When Workover reads the files itself, the source passes through Workover in transit and is not stored.

Link a repository to a project

Open the project and select Project settings.
Find the Linked repositories card.
If the workspace has more than one code host connected, select the host first.
Choose the repository from the list.

To remove one, select Disconnect next to it.

Warning: You can link more than one repository, but drafting reads only the first one linked. If a project needs a different repository for drafting, disconnect the ones linked before it so the one you want is first.

Link a public GitHub repository you do not own

If the repository is public on GitHub but not in the list, type its name (for example owner/name) in the field under the list and select Link public repo. A repository linked this way is used for AI context only. Documentation review and changelog drafting stay off for it, because they need the Workover GitHub app installed on that account.

Write a grounded draft

Name the part of the code that matters in your brief: a directory, a file, an area of the product. “Document the webhook payloads in apps/api/src/modules/webhooks” is a better instruction than “document our webhooks”, for the same reason it would be to a new engineer. It also keeps the read focused, which matters on a large repository.

When a brief might benefit from the code, Workover may ask before reading it, because a grounded draft takes a few minutes longer. Choose Check the repo to ground it, Draft now to write from the brief alone, or Edit prompt to change the brief.

While the draft runs, its card in the Drafting tray on the workspace home shows progress, such as which files it is reading. The document appears when the draft is finished.

Tell whether a draft was grounded

When you open a new draft that could not be grounded, a banner at the top of the document says so. It appears once, the first time you open the draft in the browser tab you drafted it from, so read it before you close it. The common ones:

Banner says	What happened	What to do
Not grounded in your code. A code host is connected, but this project isn’t linked to a repository	No repository is linked to the project.	Link one in Project settings > Linked repositories, then draft again.
Drafted from your prompt only … your current AI provider can’t read the repo	Your provider cannot read repositories on this code host.	In Settings > AI, choose a provider that can (see the table above), or add a second key for grounded drafts.
… the repo was too large to finish in time	The read ran out of time, so the draft is only partly grounded.	Draft again with a more specific brief that names the feature or area.
… can’t read repo. It’s private and the connection hasn’t been granted access to it	The code host connection has no access to that repository.	Grant access in Settings > Integrations.
Drafted from your prompt only. Reconnect host …	The code host connection is broken.	Reconnect it in Settings > Integrations.

What it reads

When grounding a draft, Workover AI reads files in the linked repository. Drafting does not write to the repository.

Other features use the same connection differently. Documentation review and changelog drafting read the changes in merged pull requests. Publishing to Mintlify pushes a branch and opens a pull request in your docs repository. See GitHub for what the Workover GitHub app is allowed to do.

Keep existing documents in step with the code

Drafting again creates a new document, so it is not the way to update a page you already have. To update an existing page against the code:

From the app: open the document, select Edit panel in the document toolbar, then the AI tab (the arrow-pointer icon), and select Iterate. Describe what changed. Iterate reads the linked repository when your main provider can; it does not use a second key for grounded drafts. See Revising a document with AI.
From the command line: workover doc verify <docId> checks the document against the linked repository and adds its corrections as suggestions. It needs a CLI login with workover login --draft. See CLI commands and MCP tools.

Either way, you review the changes as tracked suggestions rather than re-reading the whole page.