Repositories

An engineering agent with a story and no repository is a writing exercise. Connecting one is what makes the Development station real.

Connecting

Connect a repository from the workflow's header. The panel has a tab per host. GitHub is connected and its repositories approved in Bookbag for the organization; GitLab and Gitea connections belong to the workspace. Each workflow chooses which connected repositories it follows. Once connected, the workflow's engineering agents can read the code.

Host	What you give it
GitHub	Connect the Bookbag GitHub App in the organization’s Bookbag repository settings, then approve the repositories products may use. Choose an approved repository in CodeBook.
GitLab	A personal access token with the api scope. Self-managed GitLab takes its own API base URL.
Gitea / Forgejo	The host’s API address ending in /api/v1 and a repository access token.

Organization owners, administrators and platform administrators can open Manage in Bookbag from the GitHub tab to approve repositories and set their Writable switch. Other members choose from the repositories already approved for them.

Reading needs no separate station write grant. An authorized station worker can read the connected repository — which is what lets QA and Security review the same code the engineer changed.

Connecting starts the analysis

Connecting a repository from the workflow's header also queues an analysis of it for the System Map; attaching a repository that is already connected queues one only if it has never been analysed. The analysis lists the file tree at the default branch's head, indexes the declarations and imports of every source file, and from those derives the modules, services, endpoints, data entities, external systems, queues, tests and architecture patterns the rules recognise. The repository panel shows the phase, the files listed, read and skipped, the provider requests and the counts as the job runs, with an estimate of the time left labelled as one, and says SYSTEM MAP READY only when the whole tree was covered. A map is limited only when the provider refused a listing or a read, an administrator's cap was reached, or the tree is binary-only — with a sentence saying which. After that, a push to the default branch or a merged pull request updates only the files it changed.

Very large repositories. There is no file cap. Builds were measured end to end at 200,000 and 250,000 files; the request budget grows with the repository; vendored, built, generated and binary files are skipped by default (a pattern starting with ! takes one back); monorepo workspace packages become modules with a package picker; one organization's big build never starves another's; and a build waits out the host's rate limit rather than spending the token that pull-request sync and agent runs need. The limits and measurements are on the System Map page.

Starting a new repository does not queue an analysis by itself; Rebuild on the System Map page starts one, and so does a later push the host's webhook reports.

The analysis reads through the same connection an agent's run does and never runs the code. Its limits are listed in the implementation status.

Push webhooks

The System Map follows pushes through the repository's webhook. GitHub uses the Bookbag App’s webhook: SSO verifies the delivery and forwards it to CodeBook. CodeBook registers its own hook for GitLab and Gitea/Forgejo connections:

Host	Events	Address
GitHub	pull requests, reviews, checks, deployments and pushes through Bookbag	Bookbag SSO’s configured GitHub App webhook
GitLab	push, merge request and pipeline events	https://<your CodeBook address>/api/kanban/git/webhook
Gitea / Forgejo	pull_request, pull_request_sync, pull_request_review, push, status	the same CodeBook address

GitHub/Bookbag and Gitea deliveries use HMAC-SHA256 over the raw body; GitLab uses its configured token. Invalid authentication is refused before the delivery changes repository state. Only pushes to the map's branch — the default branch — update the map; a burst of pushes folds into one queued update. See incremental update.

CodeBook-owned hooks registered before are repaired. Hooks CodeBook installed earlier were registered without push and at an address that did not answer. Once a minute, up to five repositories per pass, CodeBook reads each older hook and, if it is one of CodeBook's, updates it in place to today's address and events, keeping every event it already had. A hook CodeBook finds at one of its own addresses but never stored is adopted. It never creates a hook and never deletes one, and a hook at the stored id that points anywhere else is someone else's and is left alone. The old address, https://<your CodeBook address>/kanban/git/webhook, is also forwarded, so a hook added by hand there keeps working.

What you see. A sentence under the build status says the hook's state — current, being updated, or a problem: no permission to manage hooks, the hook was deleted, it points elsewhere, or the host failed with its own words. For a problem, Re-register webhook installs CodeBook's hook again, push included; it is enabled for organization administrators. A new token on the connection clears a permission problem so the next pass tries again.

Starting a new repository

GitLab and Gitea / Forgejo offer Start a new repository as well as choosing one that exists. For GitHub, create the repository at GitHub and approve it in Bookbag, then select it on the workflow. On GitLab and Gitea / Forgejo, CodeBook asks the host to create it — private unless you ask for public — with a first commit, because an agent's first pull request branches from the default branch and a repository with no commits has none. The new repository is put on the workflow in the same step. An invalid name is refused before the host is asked, and a host's refusal is shown in the host's own words.

Creating a repository is a person's act. No agent and no model call can create one.

CodeBook does not host code

Your code lives in your repository host — GitHub, GitLab or a Gitea — and CodeBook reaches it through that host's API. CodeBook keeps no copy of a repository and has no code host of its own.

A Gitea or Forgejo you run

A Gitea or Forgejo you host yourself is connected from its own tab: give its API address, ending in /api/v1, and an access token created in that host under Settings → Applications with repository read and write. CodeBook does not ship or start a Gitea of its own.

CodeBook uses the host’s native branch and atomic multi-file commit APIs. An edit to the same file during a run conflicts instead of overwriting the other writer. Draft pull requests use the host’s [WIP] title convention; CodeBook checks that the host actually marked the new request as a draft. If the host has removed that draft prefix, the new request is closed with an explanation. Commit statuses and reviews come from the native REST APIs, and text patches are read separately from the changed-file list. Automatic merging remains GitHub-only.

Webhook registration reads the existing hooks before creating one. If that read fails or cannot be completed within its safety limit, registration stops; it does not guess that no hook exists.

Not a place code runs

Agents read and write through the host’s API. Executable tests and builds run only through a configured command runner or external testing service; CodeBook supplies no hosted execution machine. Without that evidence, a QA agent can review the diff but must not claim the tests ran.

Writing is per station

Changing the code is a separate permission, and it lives on the station, not on the agent:

Open draft pull requests — a switch under the station's Permissions, off by default. Commits to a new branch in the connected repository and opens a draft pull request. Never merges.

This means the same agent can open pull requests from Development and not from Code review. It also means granting it is a deliberate act against one station rather than a property somebody's agent quietly carries around the factory.

What an agent does with it

With the permission, an engineering agent commits to a new branch and opens a draft pull request linked to the card. Without it, it reads the repository and proposes — which is a perfectly good way to run the station while you are still learning what its output looks like.

It works on a new branch, and it never merges.

Start without it

The honest sequence for a new workflow:

1. Staff Development without the permission. Read what it proposes.
2. Tighten the skill and the station's instructions where the proposals are wrong.
3. Allow draft pull requests.
4. Keep a Human review station before Done regardless.

Repository memory

Conventions that belong to the code — how to run its tests, which API must stay stable — can be written once as repository memory in the workflow's Memory editor, under Primary repository. A workflow reads only its first connected repository's notes; a second repository on the same workflow adds none, and general chats and external workers never receive them. Organization owners and admins write these notes, and each approved note is pinned to the repository's identity, so repointing the connection to a different repository hides the wording until it is reviewed again. Token rotation does not. Removing the repository removes its notes. See repository memory.

Next

Pull requests — how the card tracks what the agent opened.