# Grounding drafts in a GitHub repo

Connect a repository and technical drafts are written from the code, rather than from what is plausible.

## 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.

## Connecting

Workspace settings → **Integrations** → GitHub. This installs the Workover GitHub App on the organisation or account that owns the repositories, and you choose which repositories it may read.

Install it on the **organisation**, not your personal account, if the repositories belong to a company — otherwise the connection breaks the day you change roles.

Access is read-only. Workover does not open pull requests, push commits, or comment on issues.

## Using it

Reference the repository in your brief and say what to look at: 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.

Broad prompts across a whole repository take longer — the draft runs in the background and streams in as it goes, so a large grounding pass does not time out.

## What it reads

The repository contents it has been granted: source, README files, types, comments. It does not read your issues, pull requests or CI logs.

## Keeping documentation honest

The pattern worth adopting: when an API changes, re-run the draft against the changed files rather than editing the prose from memory. The diff lands as tracked suggestions, so you review the delta rather than re-reading the whole page.

## Related

- [GitHub](/docs/github-integration)
- [Writing a good brief](/docs/writing-a-good-brief)
- [Iterating on a draft](/docs/iterating-on-a-draft)