Groups

Overview

A group is a namespace: a name in a path, a place repositories live, and the level at which you hand out access once instead of repository by repository. The top group in a chain — the one with no parent — is your organisation, and it is also the boundary the metered resources are pooled against, so storage, pipeline minutes and outbound transfer all roll up to it. Below it you nest as deeply as your teams do, granting access at whatever level makes sense and letting it flow downwards.

Use groups to give a team read access to everything it owns in one action, to keep a client's work private inside an otherwise open organisation, and to see what an organisation is consuming against what its plan allows.

Quick start

Before you start

How it works

The path is the hierarchy

Every group and every repository has one path, built by joining its name to its parent's path. Two groups under the same parent cannot share a name, and no two groups anywhere can share a full path.

Renaming platform rewrites the path of everything beneath it in the same request, so acme/platform/api becomes acme/core/api the moment the rename returns. The ids do not move. Anything addressed by id — a script holding a group or repository id, a pipeline definition, a token bound to the group — keeps working across a rename; anything addressed by path has to be told the new one, and that includes every git remote, because a remote names the repository by path.

How organisation names work

An organisation's name is the first segment of every address inside it, so to anyone reading a link, whoever holds a name is that name. Gitmoap keeps some names back for that reason, and checks an organisation's name against them whenever you create an organisation or rename one. A subgroup's name only has to be unique inside its parent.

The well-known organisations are drawn from Wikidata and the Majestic Million (Majestic-12 Ltd, CC BY 3.0): an organisation is on the list when its official website's domain is also among the most-linked domains on the web. Everyday words that happen to be brands — apple, delta, target — are kept only exactly as spelt, so apple-store is free, and names shorter than four characters, such as ibm, are kept exactly with no look-alikes refused. Places are not on the list. A name somebody already held when it joined the list stays theirs.

A name has one spelling. Names are lowercase, so Acme is never a second acme. When you look something up — a group or repository by its path, a person by username, a repository in a git clone URL — what you type is lowercased first, so Acme/Platform finds acme/platform. Creating or renaming still needs the lowercase form; put capitals in the display name.

A name you give up is held. When you rename an organisation, its old name is held for it for 90 days: nobody else can take it, and you can rename back. If the organisation has ever had a public repository or published a package, the old name is held for good instead, because people depend on what was published under it. An organisation holds at most five of its former names at a time. When an organisation is deleted, its name is held for nobody — 90 days, or for good once it published — so not even its former Owners can take it during that time. Renaming or deleting a subgroup holds nothing.

Verified domains show on the organisation. Every domain your organisation has verified under single sign-on appears on it — verified_domains on the organisation's details and in group listings — to everyone who can see the organisation, and to nobody else. It is how a reader tells your organisation from one with a similar name. A domain you have claimed but not verified never appears.

Access levels, and how they reach down

There are five levels, ordered:

Your effective level on any group is the highest level you hold on it or on any group above it. An Owner of acme is an Owner of acme/platform and of every repository underneath without holding a single row there, and a Developer on acme who is also a Maintainer on acme/web is a Maintainer there and a Developer everywhere else. Levels only ever add: a membership deeper in the tree can raise someone, never lower them. That is the one thing people get wrong — removing somebody from a sub-group does nothing if their access came from an ancestor.

The creator of a group is its Owner from the moment it exists, in the same operation, so a group is never left without one.

Visibility, and the rule that a child is never more open than its parent

Signed out, anything that is not public answers 401 — the platform asks for a credential before it will say anything else. Signed in, a private group answers 404 rather than 403 to anyone who is not a member, so its existence stays private too. If you were given a path and get 404, either the spelling is wrong or you are not in it — the response is deliberately the same either way. A Guest is a member: they see the group, and are told 403 rather than 404 for anything more, because it is no secret from them.

Visibility is constrained in one direction: a group can never be more visible than its parent. Asking for more is refused when you create the group and when you update it, and lowering a parent below a child that is more open is refused as well, naming the child that blocks it. Fix the named one first, then the parent.

The namespace is where the pooled limits live

Two kinds of limit apply, and they are counted in different places. Pooled resources — stored bytes, pipeline runs and minutes, outbound transfer — are counted against the organisation at the top of the chain, so every repository anywhere in the tree draws on the same budget. Counts of things — repositories, members, webhooks, service accounts — are counted against the individual group that holds them, so each group gets its own allowance.

Ask any group in the tree for its usage and you are told the organisation's pooled numbers. The group you named only decides which group's own counts come back beside them, and only the limits view carries those — the shorter usage view reports the organisation and nothing else.

How to

Create an organisation

An organisation is a group with no parent. You do not need to belong to anything to create one, only to have a profile. It starts private, and every provider Gitmoap publishes itself is installed on it at its latest version, so you can build a pipeline without installing anything first.

Pick the name carefully. Renaming later is one action, but it changes the path of every repository underneath it, everyone with a clone has to update their remote, and the name you leave behind is held. If the name is refused, the answer says why — see How organisation names work. If it is your own company's name, kept for whoever owns your domain, create the organisation under another name first, then take your reserved name.

Add a sub-group

A sub-group is created the same way, naming the group it sits inside. It inherits its parent's visibility unless you ask for something less open, and it cannot be more open than its parent.

Nest by ownership, not by repository count. A sub-group's real purpose is to be the thing you grant access to, so the useful shape is usually one sub-group per team or per product line, not one per repository.

Find the groups you can see

With no filter you get organisations — every one you can see, which for a signed-out caller means the public ones and for a signed-in caller adds the internal ones and the private ones you belong to. Name a parent and you get that group's direct children instead. You can name the parent by id or by path, but not both in the same request.

Groups you may not see are dropped from a page after it is read, so a page can come back with fewer groups than the limit you asked for while there is still more to fetch. Keep following the next-page token until there is none; a short page is not the end of the list. A page tops out at 100 groups however large a limit you ask for, so a script that asks for a thousand and reads one page has seen a tenth of them.

Open a group by its id or its path

Two ways in, same group. The id never changes; the path changes when the group or any of its ancestors is renamed.

Prefer the id in anything you store. Prefer the path in anything a person types. The CLI takes either wherever it asks for a group: a value shaped like an id is used as one, and anything else is looked up as a path.

The whole path travels as a single value, slashes and all, so let the CLI or a generated client build the request rather than pasting acme/platform into a URL by hand.

Rename a group or change its details

Display name, description and avatar reference are ordinary metadata. The group_name is not: changing it recomputes this group's path and rewrites every descendant group and repository path in the same request.

Fields you leave out are left alone, so a request carrying only group_name changes only the name. To clear a display name or description, send it as an empty string rather than omitting it. If the new name is taken by a sibling group, or the new path by any other group, the rename is refused and nothing moves.

Renaming an organisation needs Owner, and its new name is checked the way a new organisation's is — except that a domain the organisation has verified unlocks the name kept for that domain. The old name is held for the organisation: for 90 days, or for good once it has published, and never more than five at a time. Sending the name the organisation already has is not a rename.

Take your reserved name

A well-known organisation's name is kept for whoever proves they own its domain, and the proof is the DNS record you publish to verify a domain under single sign-on. Verify the domain on an organisation you already have, then rename that organisation into the name.

1. Create your organisation under any free name, or use one you already own.
2. Claim and verify, on that organisation, the domain the refusal named — see Verify a claimed domain. A domain beneath it works too: microsoft is unlocked by microsoft.com or eu.microsoft.com, and never by a domain that only contains the name, such as microsoft.mooo.com.
3. Rename the organisation to the name, as an Owner.

The same domain unlocks the names that look like yours, so microsoft-support is yours to take as well. Only an organisation renaming itself is ever unlocked this way: a new organisation, a username and a personal group never are, which is why you create first and rename second. Releasing the domain later does not take the name back. If verifying the domain answers 501, domain verification is unavailable on Gitmoap's side — contact support@gitmoap.com.

Change who can see a group

Visibility is the one metadata change that needs Owner, and it is checked in both directions: not more open than the parent, and not more closed than a child that is already more open.

Going from private to internal or public exposes the group's name, description and its public contents to people who were never members. It does not open the repositories inside it — each keeps the visibility it already had. Going the other way is refused while a sub-group or repository beneath it is still more open, and the refusal names the one that blocks you.

Set or remove a group avatar

Uploading is two steps: ask for an upload URL, then send the bytes to it. The request declares the exact size of the file, and that size is bound into the URL — sending a different number of bytes is refused by the storage service, so a small declaration cannot smuggle a large upload.

The response carries two URLs: one to PUT the bytes to, which is valid for five minutes, and the address the image is served from afterwards. That second address is fixed for the life of the group, so uploading again replaces the image in place and nothing that already points at it has to be updated. Removing the avatar deletes the image, and the address stops serving one.

Add someone to a group

Adding is create-only and names the level you want them at. Maintainer is enough for every level except Owner, which needs Owner. The request identifies the person by their account id, not by an email address, so a script adds people in two steps: look the account up by username or email, then add the id it gives back.

Three refusals are worth knowing before you hit them. The person must already have an account — there is no way to add an address that has never signed in. Adding somebody who is already a member is refused rather than silently changed; change the level instead. And each group has its own member cap for the plan, counted against that group alone, not against the organisation.

Add at the lowest level that works, but not lower. Guest lets somebody see that a private group and its repositories exist — their names, and nothing inside them. Reporter is the lowest level that reads a private group's content and the repositories in it.

See who is in a group

The list shows direct members of this group only. It does not show the people who reach it from an ancestor, which is the usual reason a group appears to have fewer members than it behaves as having. It lists people; the service accounts a group owns are listed separately and counted against a separate cap.

You need Reporter or above on the group to read its members — even when the group itself is Public or Internal. Who has access to a group is not part of what the group shows the world, so a signed-in person without a membership gets a 403, and a visitor who is not signed in is asked to sign in.

To answer who can actually touch this?, read the members of every group on the path above it as well.

Each row names the person by account id and level, not by username, so a report that has to print names resolves each id through the users API. The filter still matches on username and email even though neither comes back in the row.

Check one person's access

A 404 here means they hold no membership on this group. It is not an answer about whether they can reach it — they may hold one on an ancestor. Like the list, it needs Reporter or above on the group.

Change someone's access level

Promoting somebody to Owner, or moving an existing Owner to anything else, needs Owner. An organisation — a top-level group — always keeps at least one Owner, so demoting its last one is refused: promote a second Owner first, then demote the first. A subgroup may be left with no direct Owner, because the organisation's Owners always administer it.

Remove someone from a group, or leave it yourself

You can always remove yourself, at any level, without needing permission to manage members — with one exception: the last Owner of an organisation cannot leave it, because that would strand the organisation with nobody able to administer it. Leaving a subgroup as its last direct Owner is fine.

If somebody still has access after you removed them, their access is coming from a group above this one. Remove the membership where it actually lives.

See the groups you belong to

This is your own list, and only yours — asking for somebody else's memberships is refused.

Membership inherited from an ancestor does not create a row here, so a group you can administer through its parent will not appear. The parent will.

Check usage against your limits

Two views, different shapes. The usage view is the short one: storage, pipeline runs in flight, runs and minutes this month, and the plan the organisation is on. The limits view is the complete one: everything metered across the organisation, plus the live counts for the group you named, plus the caps that apply to individual repositories, merge requests and issues.

Name any group in the tree where you are Reporter or above — the organisation-wide numbers are the same from anywhere in it, and they are never public, whatever the group's visibility. What changes is the second table, which counts this group's own repositories, members, webhooks, service accounts and the rest.

Check outbound-transfer usage

Bytes leaving the platform — clones and fetches, downloaded release assets and archives, published packages people pull — are metered per day for the whole organisation against a cap that comes from your plan.

The window is a UTC day, named in the response, and it resets on its own; there is nothing to clear. A big first clone of a large repository is the usual reason a number jumps — a shallow clone (git clone --depth 1) moves far fewer bytes, and a build agent that clones on every run is worth pointing at a cache.

Delete a group

Deleting is Owner-only and refuses while anything is still nested inside. Move or delete the repositories first, then the sub-groups, working from the leaves upwards.

Deleting an organisation gives its slot back straight away — to the account that created it, which is not necessarily the Owner doing the deleting.

Reclaim an organisation's name

This one belongs to Gitmoap's platform administrators, not to an organisation's Owner. It is how Gitmoap acts on a report that an organisation impersonates somebody, or that its name infringes a trademark or another right somebody holds in it. To make such a report, write to the legal desk through the contact form.

The administrator records the reason, impersonation or infringement, and a note of what the reclaim rests on, and the organisation's Owners are sent the reasons before the name is taken. If the name is held for your organisation, rename your organisation to it the way you would to any free name. The other checks still apply, so a well-known organisation's name also needs its domain verified first.

Reference

Limits

Three caps apply directly to what this page covers. All three refuse the request outright when you reach them — nothing is half-created, and no counter moves.

The member cap is per group, not per organisation, so a hundred-person company can run ten fifty-member teams on a plan whose cap is fifty. It counts the memberships written on that group — including the creator's Owner membership, which is there from the moment the group exists — and nothing else: people who reach the group through an ancestor do not occupy a slot, and neither do the group's service accounts, which have a cap of their own (10 on Free, 50 on Pro, 200 on Team, 1000 on Enterprise).

The organisation cap is per account and follows the person who created the group, not the group.

Three more caps shape a hierarchy and are worth knowing before you build one. Repositories and storage are reported by the usage views above; outbound transfer has its own view, because it is a rate rather than a level and is measured over a day:

An Owner files an increase request against the organisation, naming the one limit and the value wanted, and it is reviewed before anything changes. An approved increase to a pooled or per-group limit applies to that organisation alone, and the new number appears in the limits view as soon as it is applied, because the view reports the limit enforcement actually uses. The organisations-per-account cap is the exception: it belongs to an account rather than to a namespace, so no group's limits view reports it — the only way to see where you stand is that creating one more either works or answers 429.

Troubleshooting

FAQ

Related