Repositories
The Repositories tab of a project's Code pages: the Git repositories the code lives in, with provider, owner, name, default branch, privacy and component; registering, editing, disconnecting and deleting them.
By the end of this page you will have registered where a project's code lives, know every field a repository carries and what reads each one downstream, and know how a repository is set aside, brought back and, when it must be, deleted.
A repository is a Git repository a project's code lives in: its provider, the account or group that owns it, its name, the branch releases are cut from, whether it is private and which component it builds. The registry is kept by hand for now; once Git hosting is connected the same rows carry the connection, and branches, commits and pull requests hang off them to link work items to code. Releases will read the default branch, deployments will name the repository, and Heimdall names it when it drafts a branch name for a story.
The Repositories tab is the first of the project's Code pages; branches and pull requests join it when Git hosting lands.
Before you begin
| You want to | You need |
|---|---|
| Open the Repositories tab | repository:view-any on the project. Every staff role has it; a client guest never does, and is refused at the door. |
| Register a repository | repository:create, through your role on the project or your team role, or to own the team. Developers have it by default. |
| Edit, disconnect or reconnect one | repository:update. |
| Delete one | repository:delete. |
The page lives under a project: open the project and choose Code in the sidebar. A client guest does not see the entry, and the page answers them with a refusal.
Read the repositories
The table lists one repository per row, by full name:
| Column | What it shows |
|---|---|
| Repository | The full name in the provider's spelling with the address beneath it, a Private badge when the code is private and a Disconnected badge when it is set aside. Press the name to open the detail flyout. |
| Provider | Where it is hosted: GitHub, GitLab or Bitbucket, as a coloured badge. |
| Component | The component it builds, or Whole project. |
| Default Branch | The branch releases are cut from. |
| Updated | How long ago the record last changed. |
| Row menu | View Repository, Open at Provider, Edit Repository, Disconnect Repository or Reconnect Repository, Activity, Delete Repository. |
Sort by repository, provider, default branch or updated by pressing a column heading; press it again to flip the direction. Above the table, narrow the list with the search box (words in the full name, the address or the default branch), the provider filter, the component filter and the Disconnected switch, which shows disconnected repositories instead of live ones. The filters travel in the page address; Clear Filters on the empty state drops them all.
Register a repository
- Press Register Repository.
- Pick the Provider and type the Owner (the account or group) and the Name as the provider spells them. The Address is derived from them; fill it in only for a self-managed host.
- Under How It Is Used, set the Default Branch releases are cut from, pick the Component the repository builds or leave it as the whole project, and say whether it is a Private repository.
- Press Register Repository.
The repository appears in the table at once, you are recorded as the person who registered it,
and repository.created goes out to every endpoint subscribed to it.
The registry comes before the connection
Registering a repository writes down where the code lives; it does not read the code. Connecting Git hosting, which links branches, commits and pull requests to work items, arrives with the Git integration and attaches to the rows you register here, so the registry is worth filling in now.
Open a repository
Press a repository's name, or View Repository in its row menu, to open the detail flyout: the provider, privacy and disconnected badges, the full name and address, Open at Provider, the Default Branch, the Component, who Registered it and when, and the updated or disconnected stamp. From the flyout, Edit, Disconnect or Reconnect, Activity and Delete are one press away.
A link such as /projects/<project>/code?show=<id> opens the tab with that repository's flyout
already open; notifications and Heimdall's buttons use it.
Edit a repository
- Press Edit Repository in the row menu, or Edit in the flyout.
- Change what you need. A new owner or name must leave the full name free within the project for that provider; clearing the address falls back to the provider's own.
- Press Save Changes.
Every change travels as repository.updated with its old and new values. An edit that changes
nothing announces nothing.
Disconnect, reconnect and delete
- Disconnect Repository sets the repository aside: it leaves the default view and the live listing while its row and history stay, and no branch, commit or pull request will be read from it. Switch on Disconnected above the table to find it.
- Reconnect Repository brings a disconnected repository back into use.
- Delete Repository removes the registration with its activity history after a confirmation; there is no undo. The code itself stays with the provider. Branches, commits and pull requests are not here yet; once they are, a repository with code references will be disconnected rather than deleted.
All the fields
What happens next
- Every register, edit, disconnect, reconnect and delete is written to the repository's activity history with who did it and where from.
- The
repository.created,repository.updated,repository.disconnected,repository.reconnectedandrepository.deletedevents go out to every endpoint subscribed to them. - The Git integration will attach to these rows, and releases and deployments will name them, as those modules land.
Heimdall on this page
Heimdall reads the repositories through the same tools the MCP server offers and carries the open project as its context.
Registering repositories is a person's work: an agent over MCP reads the registry to clone, branch and name repositories correctly, and never rewrites it.
From the API and MCP
Repositories API
List, get, register, change, disconnect, reconnect and delete repositories over REST.
list_repositories and get_repository
The two MCP tools that read a project's repositories as the token sees them.
Permissions
| Action | Permission |
|---|---|
| See the repositories | repository:view-any; a client guest is refused |
| Open a repository | repository:view |
| Register a repository | repository:create, or owning the team |
| Edit, disconnect or reconnect | repository:update, through a project role or a team role |
| Delete a repository | repository:delete |
Frequently asked
Related
- Components — what a repository builds
- The project overview — the project the repositories belong to
- Status reference — the three providers
repository.*webhook events
How is this guide?
Last updated on
Design References
The Designs page of a project: the links it keeps to Figma files, wireframes, prototypes, screenshots, API contracts and diagrams, attached to the whole project or to one component.
Project Settings
The Settings page of a project: cadence, estimation, workflow, collaboration and alert knobs with their defaults, plus the danger zone.