Data in your own repository
What it is
Normally onlybrain hosts a brain: the files and the whole history are at onlybrain on an encrypted disk. A company that wants to keep the data itself connects its own git repository.
- The repository is the source of truth. It holds all the brain's files and its whole history.
- onlybrain writes to it. Every change from the app, Claude Code, Codex or the connector is pushed to the repository by onlybrain.
- onlybrain takes in changes from the repository. What somebody pushes straight to the repository shows up in onlybrain.
- Nothing changes for people. Roles, sharing, search, the onlybrain app and the connector work just like with a hosted brain.
Supported services: GitHub, GitLab (gitlab.com or a self-managed server) and other git over HTTPS (Gitea, Bitbucket, Azure DevOps).
Connecting a repository
A brain manager connects it in Settings, section Where the data lives, with Connect your own repository. A new brain straight from a repository is made on the Upload your own brain page with the option Connect a git repository. No brain type is chosen, the AI proposes one (see below).
Connect a git repository is a lasting connection: the data stays in the repository and onlybrain stays connected to it until it is disconnected in Settings → Where the data lives. Upload from a file, on the other hand, is a one-off copy that onlybrain hosts from then on.
- Service. Choose GitHub, GitLab or other git.
- Address and token. Paste the repository's HTTPS address (the Code or Clone button) and an access token with rights to this repository only:
- GitHub: a fine-grained token at github.com/settings/personal-access-tokens/new. Repository access: Only select repositories, just this one. Permissions: Contents - Read and write (GitHub adds Metadata read itself).
- GitLab: a project access token in the project's Settings → Access tokens. Role Maintainer (a Developer cannot push to a protected main branch), scopes read_repository and write_repository.
- Gitea: Settings → Applications, a token with repository Read and write.
- Bitbucket: a repository access token with the scope Repositories: Write, user name
x-token-auth. - Azure DevOps: a personal access token with the scope Code: Read & write, any user name.
- Check. onlybrain checks the address, reading, writing, the default branch and the history and shows the result of each step. Connect pushes the brain's whole history to the repository, so the repository must be empty or already hold the same history.
- What onlybrain writes. Below the check is the list of files onlybrain writes to the repository. Going on takes ticking I understand that onlybrain writes these files to the repository.
The token is stored only at onlybrain, encrypted. It does not stay in the browser. Change the access token replaces it any time, for example when it expires.
What onlybrain writes to the repository
When connecting, and when making a brain from a repository, onlybrain adds what it needs for roles and for AI tools. The wizard shows the exact list for the repository before confirming.
.onlybrain/: roles (roles.yml, only when the repository has none yet), the brain's description for onlybrain (manifest.json) and onlybrain settings.AGENTS.md: instructions for AI tools.- Files for Claude Code and Codex:
CLAUDE.md,.claude/and.agents/pointing to the skills and agents, without symlinks. README.md: only in an empty repository.
The files come as new commits straight to the main branch, without a pull request. When the main branch is protected and the access token cannot write to it, connecting stops. The token then needs the right to write to the main branch (in GitLab the Maintainer role).
A structure proposed by AI
After a brain is made from a repository (or uploaded from a file), onlybrain offers Propose a structure with AI. The AI goes through the repository's content (the folder tree, README, AGENTS.md and CLAUDE.md, samples of documents, not the whole content) and proposes a brain type, roles, AGENTS.md, agents and skills that fit the content. When the repository has no AGENTS.md yet, the proposal starts on its own.
The proposal comes as a change to approve in Changes. Until a manager approves it, nothing changes in the brain or the repository. The whole proposal or only some files can be approved.
Webhook
Without a webhook onlybrain fetches changes from the repository at intervals of a few minutes (the settings show the exact interval). With a webhook changes show up in onlybrain right away. The webhook's address and secret are in Settings → Where the data lives → Webhook, each with a copy button.
- GitHub: in the repository Settings → Webhooks → Add webhook. Payload URL: the webhook address, Content type:
application/json, Secret: the secret, Which events: Just the push event. - GitLab: in the project Settings → Webhooks → Add new webhook. URL: the webhook address, Secret token: the secret, Trigger: Push events.
- Gitea and Bitbucket: a webhook on push with the same address and secret.
- Azure DevOps and others: nothing to set up, changes are fetched at intervals.
Generate a new secret makes the old secret stop working right away. The new one then has to go into the repository's webhook too.
What is where
- In the company's repository: all files and the whole history. The repository is the source of truth.
- At onlybrain: a working copy for roles, search and the connector, on an encrypted disk.
- At AI providers: content passes through them when people work with Claude or Codex, just like with a hosted brain.
Disconnect brings the brain back to onlybrain: it stays there with all its files and history, and onlybrain hosts it again. The repository stays as it is, onlybrain stops writing to it and the access token is deleted. onlybrain's copy is deleted only when the brain is deleted; the repository stays even then.
Pushing straight to the repository
The repository also takes pushes without onlybrain, for example from a computer or from CI. The change shows up in onlybrain after the webhook, or within a few minutes without one.
- Roles still apply. Whoever works through onlybrain sees and changes only what their role allows, also for files that came straight from the repository.
- Direct access to the repository is outside the roles. Whoever has rights in GitHub or GitLab itself sees the whole repository. Access to the repository belongs only to people who should see everything.
- Default branch. onlybrain works with the repository's default branch (usually
main), shown in the settings.