Repositories

Overview

A repository holds your code and everything the platform knows about it: who may read and write it, what it is written in, who has contributed, and every commit, tag and file in its history. You create one inside a group, push to it over git, and from then on you can read it without a clone — a file at a ref, a page of history, the tag a release was cut from — and hand out access one person at a time.

The same repository is also the unit almost everything else attaches to. Merge requests, work items, pipelines, releases, branch rules and service accounts all live inside one, so getting its group, its visibility and its members right is the thing you do first and rarely have to revisit.

Quick start

Before you start

How it works

Where a repository lives, and what its name means

Groups nest, repositories do not. A repository's full path is its group's path plus its own name, and that path is unique across every group and every repository on the platform — so a group and a repository can never claim the same one.

The path is a display and navigation concern. The id is the identity: it never changes, not when you rename the repository, not when you move it to another group. That is why the API takes ids — a script holding an id keeps working through a reorganisation, and a script holding a path breaks the moment somebody renames a group above it.

Who can do what

Two things decide it, and they are independent.

Visibility decides who can read at all. A public repository answers anyone, signed in or not. An internal one answers anyone signed in. A private one answers only its members, and answers everyone else 404 rather than 403 — so a stranger cannot use the API to discover that a repository exists. A repository can never be more visible than the group above it; the platform refuses the change rather than quietly widening the group.

Access level decides what you can do once you are in. The five levels are ordered — Guest, Reporter, Developer, Maintainer, Owner — and your effective level on a repository is the highest of your direct membership on it and your membership on any group above it. A Developer on acme/platform who is also a direct Maintainer on acme/platform/checkout is a Maintainer there.

The member list shows direct members only. Somebody who reaches the repository through a group is not on it, and removing their direct membership does not take away what the group gives them.

Git data is read live

Commits, tags and files are not a second copy kept in step with git — they are read out of the repository itself on every request. That has one consequence worth knowing: what you read is exactly what a clone would show, including after a force-push, and there is nothing to resynchronise when history is rewritten.

Because file and tree reads are addressed by a ref, asking for main gets you an answer that changes when main does. Ask by commit sha and the answer can never change, which is why a request naming a branch may be pointed at the same request pinned to the commit the branch resolves to. Send If-None-Match with the value you got last time and an unchanged ref costs you a header exchange instead of a body.

Two reads on this page are not live, and knowing which saves you a confusing minute. The contributor list and the language breakdown are maintained as your pushes land rather than recomputed when you ask, and both describe the default branch only. The language breakdown names the commit it describes, so you can always tell how current it is, and it rebuilds itself whenever a push is not a clean continuation of what it last indexed. The contributor list has no equivalent repair: a force-push that rewinds the default branch leaves it crediting commits nothing reaches any more.

How to

Create a repository

You need Maintainer on the group it goes in. The name is a slug — lowercase letters, digits and hyphens, one to a hundred characters, no leading or trailing hyphen — and the display name is the free-text one people read. Leave visibility out and the repository inherits the group's; set it and it must be no wider than the group's.

You are added as Owner in the same act, so a repository can never exist without somebody able to manage it. It is created empty, with main as its default branch.

Then push into it:

Find a repository

Listing is scoped to one group, and you name that group either by id or by path — one of the two, never both. You get back everything in that group you are allowed to see: a member of the group sees its private repositories, a signed-in stranger sees the public and internal ones plus any private one they are a direct member of, and an anonymous caller sees only the public ones. For a signed-in caller who is not a member of the group, private repositories are dropped after the page is cut, so a page can come back shorter than the limit you asked for. Follow next_token until a response carries none, rather than reading a short page as the end of the list.

To read one repository, use its id. What comes back is the repository's own record — its path, display name and description, its visibility and default branch, its star count and its measured size — and empty, which is true while the repository has no branch and no tag. Read empty before you ask for files: a repository nothing has been pushed to has no tree at any ref, so the thing to show is how to push to it. remote_url is the address to push it at: gitmoap:// and its path, with Gitmoap's host in front. Print it rather than assembling your own.

To go from a path a colleague pasted into a chat, use the by-path read.

When you do not know whether a path is a group or a repository — building a breadcrumb, or handling a pasted link — resolve it first. The resolver answers with the type and the id, and follows the same visibility rules as everything else.

List the repositories that are yours

Two personal listings, and they answer different questions. One returns every repository you reach through membership — direct, or through any group above it — most recently active first. A public repository you can read but have no membership on is not yours and does not appear.

The other returns the repositories you starred, most recently starred first.

Rename a repository or change its description

Renaming changes the full path immediately, and the old path stops resolving — anything that hard-codes it, including a git remote, needs updating. The id is unaffected, so anything holding the id keeps working. If the new path is already taken by a group or a repository, the rename is refused and nothing changes.

Change who can see a repository

Visibility is the one setting on this screen that needs Owner rather than Maintainer, because widening it publishes code — and Owner is what the change costs in both directions, narrowing included. Narrowing is otherwise unconstrained; widening reaches only as far as the group above allows, so a private group cannot hold a public repository, and the request is refused rather than partially applied.

Give a repository an avatar

Uploading is two steps: ask for an upload link, declaring the exact byte size and content type, then send the image to that link. The size you declare is bound into the link, so a file that grew between the two steps is rejected rather than stored. Images may be PNG, JPEG, GIF or WebP, and at most 5 MiB. The link expires five minutes after it is issued, so upload straight away rather than holding on to it.

Removing the avatar deletes the image you uploaded.

Add someone to a repository

Adding a member is create-only: if they are already a direct member, the request is refused and you change their level instead. Adding somebody at Owner needs you to be an Owner; every other level needs Maintainer. The person has to have an account already — there is no invite-by-email on this call.

Adding a direct membership never takes anything away. If they already reach the repository as a Maintainer through a group, adding them as a direct Reporter changes nothing about what they can do, because the effective level is the higher of the two.

See who has direct access

The member list is direct memberships only, with the level and when it was granted. Use the search fragment to narrow by username or email when a repository has a long list. Reading it needs Reporter or above on the repository, whatever its visibility: a public repository shows its code to everyone, not who works on it.

To check one specific person — a permission bug report, usually — read the single membership rather than paging the list.

Change or remove someone's access

Raising or lowering a level is one call. Any change that touches the Owner level — granting it, or taking it away from somebody who holds it — needs Owner; every other change needs Maintainer. A repository may be left with no direct Owner: the Owners of its organization — the top-level group — always administer it, so demoting the last one strands nothing.

Removal is symmetric. You may always remove yourself without any elevated permission — leaving is not a privileged act — even as the last direct Owner. Removing a direct membership leaves any access the person has through a group untouched.

To see what one person is a direct member of, read their repository memberships. This one is self-only: you can ask about yourself, and nobody else.

Browse the files

A tree listing takes a ref — a branch, a tag or a commit sha, defaulting to the repository's head — and a directory path, defaulting to the root. Entries come back as files or directories with their size and mode, up to a hundred per page.

A ref that names nothing is 404 NOT_FOUND — unless the repository has no branch and no tag at all, in which case a tree listing, its commit column and a file read all answer 409 REPOSITORY_EMPTY instead, whatever ref you name. The two ask different things of you: the first means pick another ref, the second means push something first. The repository's own empty tells you the same before you ask.

Reading a file gives you its contents, marked as text or as base64 when it is binary, with its size, its mode, and the two ids a later commit needs: the file's blob_sha and the commit_sha the ref resolved to. Text that is not valid UTF-8 comes back with lossy set — the bytes that could not be decoded are shown as replacement characters, so a copy of that content is not the file. Files over 1 MiB are refused rather than truncated — clone the repository or read them through git for those. To change a file without a clone, see Edit files in the browser.

See what a repository has

The licence is recognised by its text, compared with the common licences — MIT, Apache-2.0, the GPL family, the BSD licences and the others offered as templates — and named with its SPDX identifier. A licence that is none of them is shown as a licence file without a name, never as the nearest one.

Search the code

A search finds text in the files at a ref and returns each matching line with the two lines either side of it, the file it is in and its line number. The text is matched literally; pass regex=true to use a regular expression instead, and ignore_case=true to ignore case. Give one or more path values to search only those files or directories.

The answer names the commit it searched, so you can search again at exactly that commit. A search returns at most 200 matches and stops early on a very large result or after a few seconds; when it does, truncated is true and more matches may exist — narrow the search with a path or a more specific pattern to see them. Binary files are not searched.

See when each file last changed

A tree listing tells you what is in a directory. A second request tells you what happened to it: for every entry, the last commit that touched it, and for a directory entry, the last commit that touched anything inside it. It also returns the last commit for the directory you are looking at, which is the line most file browsers put above the table.

Ask for the same ref, path, limit and page you asked the tree listing for, and the two responses line up entry for entry. Each row carries its path, so you can match on that instead of on position if you prefer.

This is the one read here that has to search backwards through history, and how far back depends on the directory: files people change often are answered in a moment, a file nobody has touched in years takes longer to find. The search gives up rather than running indefinitely, and when it does the response sets truncated and the entries it did not reach come back with no commit. That means not found yet, never never changed — every file in a repository was added by some commit.

The search stops for one of two reasons, and they are kept differently. A search that reached its limit on how many commits it reads stops at the same commit every time, so that answer is kept, and asking again for the same commit is fast. A search that ran out of time is not kept: the response says not to store it and carries no ETag, so asking again searches again, and the second search usually gets further. A file moved from one directory to another counts as a change to both.

Read the history

History is listed from a ref, newest first, and includes every commit a merge brought in: merge a branch without squashing and its commits appear under their own authors and dates, with the merge commit above them. Each commit carries its author and committer — separate identities, because a rebase or a cherry-pick keeps the original author — the message, its parents, and any tags pointing at it.

To see each merge as a single entry instead, ask for first_parent=true. Only the first parent of each commit is followed, so the commits a merge brought in drop out and the history reads as what landed on the branch, one merge at a time.

Add a path and you get the history of one file or one directory instead of the whole repository. A change made on a branch and merged in is credited to whoever wrote it, on the day they wrote it, not to whoever pressed merge. Combine it with first_parent=true and you get the merges that brought changes to that path instead.

Pass next_token back exactly as you received it, with the same first_parent: a token from one kind of listing is refused by the other. A page deep into a long history takes longer than the first, because it is found by counting from the newest commit, and a push between two pages can show a commit twice where they meet.

A single commit can be read by full sha or by an abbreviation of at least seven characters. An abbreviation matching more than one object is treated as not found, so use the full sha in anything automated.

Tag a commit

Creating a tag needs Developer. Give it a name and a target — a commit sha or a branch name, resolved when the request arrives. Include a message and you get an annotated tag carrying you as the tagger and the date; leave the message out and you get a lightweight tag, which is just a name pointing at the commit.

Tags are immutable here, as they are in git: there is no update. Moving one means deleting it and creating it again, which is deliberate — a tag that silently moves makes a release unreproducible.

Listing tags supports a name filter and sorts by name ascending or descending; each entry carries the commit it points at.

Delete a tag

Deleting needs Developer, the same level as creating, and it is refused if no tag by that name exists.

See what a repository is written in

The language breakdown is kept up to date as you push rather than computed when you ask, so it comes back with the commit it describes and the time it was written. Vendored code, generated files, documentation and everything the classifier could not place — binaries, symlinks, submodules, data and prose formats — are excluded from the bar and counted separately by reason, so a bar dominated by one language is explicable rather than mysterious. A repository that has never been indexed answers with an empty breakdown and no commit, which is a different thing from a missing repository, and a very large tree can be indexed only in part — the reply says so rather than quietly under-reporting.

In a repository holding several services, the same breakdown is available for the paths one service owns, which is the useful number in a monorepo. A service spanning more than one repository reports the commit each was indexed at separately, since they are indexed independently.

See who has contributed

Contributors are derived from the commits on the default branch, ranked by commit count, with additions, deletions and the first and last time each person committed. Work on a branch that has not landed credits nobody; merging it credits the original authors, since their commits become reachable at that moment. Co-authored-by: trailers are counted, so pairing shows up — a co-author is credited with the commit and with no lines, which is why the commit counts across a repository add up to more than the commits it holds while the line counts add up to exactly the diff it received.

Contributors are keyed by the email in the commit. When that address matches an account the entry is linked to it, and when it does not the person is still listed — an outside contributor is a contributor. The link is made when you read, so somebody who signs up long after their commits landed appears linked on the next request with no backfill.

For one merge request, the participant list is the other question — everybody who authored, reviewed, approved, commented, reacted, wrote a commit, was credited as a co-author, merged or closed it, each appearing once with every role they hold.

Look at a contribution heatmap

A heatmap is the per-day count of commits, merge requests, reviews, releases and work items credited to one person, over a range you choose: a whole calendar year, or an explicit start and end no more than 366 days apart. Ask for no range at all and you get the trailing 365 days ending today. It comes back with the daily cells, the totals by type, the busiest single day and the current and longest streaks. Commits are credited to their author on the author's date, not to whoever pushed them; a work item counts once when it is filed and again when it is closed.

Your own heatmap counts everything you have done.

Somebody else's is filtered to what you can see: work in repositories and groups you have no access to is not counted, so the same profile shows different totals to different viewers.

Service accounts are contributors too — automation that opens merge requests and publishes releases builds a history like anybody else. Reading one needs access to the service account itself.

Star a repository

Starring is a private bookmark and a public count. It needs only the ability to see the repository, so anyone signed in can star a public one. Starring twice is the same as starring once — the call succeeds either way and the count moves only on the first — so a retrying script cannot inflate anything.

Checking a star answers starred: true, with the moment you starred it in starred_at, or starred: false. Not having starred a repository is an answer rather than an error, so the check never answers 404 for it.

Starring, unstarring and checking a star all need that same read access. A private repository you have since been removed from therefore answers 404 to all three, and it drops out of your starred list at the same moment, because that list is filtered to what you can still see. Unstarring something you had not starred is reported as not found too.

Propose a CODEOWNERS file

A repository with no CODEOWNERS file still has owners, because the service catalog knows which paths belong to which service and which group owns each service. This read renders the CODEOWNERS text those bindings would produce, so you can review it in a merge request and commit it yourself. Nothing is written to your repository — the platform proposes, and the repository decides.

The response tells you whether a CODEOWNERS file already exists on the default branch, which is the thing to check first: an existing file wins wherever it matches, so committing this one over it is a merge rather than an adoption. The rule count covers bindings whose service has an owner; paths whose service has none appear as comments and are not counted.

Move a repository to another group

A transfer changes which group the repository belongs to, and with it the inherited permissions: people who reached it through the old group's hierarchy lose that access, and people in the new one gain it. Direct members are untouched. The full path changes, so remotes and links pointing at the old one need updating; the id does not, so nothing holding an id breaks.

You need Owner on the repository and Maintainer on the destination group. The repository must not be more visible than its new parent — narrow its visibility first if it is — and its path must be free at the destination. Its stored bytes move to the destination's namespace budget, so a transfer into a namespace with no room is refused rather than half-applied.

To see who would gain or lose access before you move anything, ask for a preview with the same destination. It lists each person whose access would change, with what they would gain and lose, and moves nothing. Grants made on the repository itself move with it, except across organisations, where a team's grant, a custom role's grant and a service account's grant cannot follow.

Delete a repository

Deleting needs Owner on the repository. The repository's stored bytes are returned to its namespace's budget. Work items in other repositories or groups that referenced this repository's commits survive, with those references removed.

Reference

Repositories themselves — creating, reading, changing, moving and deleting one.

The two personal listings, answering "what is mine" and "what did I star".

Stars.

Direct membership. Access through a group is resolved, not stored, so it appears in none of these.

Files and history, read live from git.

Tags.

What the code is made of, and who made it.