Groups, subgroups, projects
Intermediate GitLab UI
Why this matters
Where a project sits decides who can see it, who can push to it, and what its URL is. On a small team this is one group and a handful of projects; in a large company it is a tree several levels deep, and knowing how to read it saves a lot of asking.
The three levels
A subgroup is simply a group inside a group, and they nest as deeply as you need (up to twenty levels, far more than anyone should use).
The path is the URL
Names join with slashes, and the result is both the URL and what GitLab calls the namespace:
| Thing | Path | URL |
|---|---|---|
| Group | northwind-trails |
gitlab.com/northwind-trails |
| Subgroup | northwind-trails/docs |
gitlab.com/northwind-trails/docs |
| Project | northwind-trails/trailguide |
gitlab.com/northwind-trails/trailguide |
| Project in a subgroup | northwind-trails/docs/style-guide |
gitlab.com/northwind-trails/docs/style-guide |
The clone URL is the same path with .git on the end. So a colleague pasting gitlab.com/northwind-trails/docs/style-guide tells you, without another word, that there is a group, a subgroup for documentation, and a project inside it.
Personal projects live under your username instead: gitlab.com/your-username/trailguide. That is where your practice project from Lab 2 lives, and it is why work projects should be created in the team's group rather than in your own namespace.
Membership flows downwards
This is the part with real consequences. A member of a group has their role in every project inside it, including projects created next year. Members can also be added directly to a project, and the effective access is the highest of the two.
| You are added to | You get access to |
|---|---|
The group northwind-trails as Developer |
every project in the group and all its subgroups, as Developer |
The subgroup northwind-trails/docs as Developer |
every project in that subgroup only |
The project trailguide as Developer |
that project only |
The practical advice follows: ask to be added at the level that matches your work. A technical writer working across all the team's documentation belongs in the group; a contractor on one project belongs in the project.
Finding your way
The path in a clone URL tells you the structure:
$ git remote -vorigin https://gitlab.com/northwind-trails/trailguide.git (fetch)
origin https://gitlab.com/northwind-trails/trailguide.git (push)Group northwind-trails, project trailguide. If a project moves to another group, its URL changes; GitLab redirects for a while, and git remote set-url makes it permanent (lesson 7.4).
The GitLab Workflow extension lists the projects you belong to once you give it a token, so cloning from within VS Code shows the group structure as a searchable list.
Without the extension, paste the URL into Git: Clone.
With a GitLab account added under Settings → Version Control → GitLab, Get from VCS lists your projects grouped by namespace, which is the same tree.
- The top bar's Search or go to finds any group or project you belong to; typing a few letters is faster than browsing.
- Your work → Projects and Your work → Groups list everything you are a member of.
- Inside a group, the Subgroups and projects tab shows its contents; a project's page shows its full path under the name.
- To create: New project or New subgroup from the group's page, so the thing lands in the right namespace from the start.
The equivalent tree is shallower: an organization owns repositories, with teams for grouping people rather than projects, and no subgroups. So github.com/northwind-trails/trailguide is an organization and a repository, and the nesting stops there. See lesson 10.2.
Common mistakes
- Creating a work project in your personal namespace. Access then has to be granted person by person, and it looks like your project rather than the team's. Moving it later changes the URL.
- Asking for project access when group access is meant. You get one project and have to ask again next week.
- Assuming a project you cannot see does not exist. Private projects are invisible to non-members; the URL simply looks like a missing page (lesson 9.3).
- Hard-coding a URL that later moves. GitLab redirects an old path for a while, but
git remote set-urlis the fix.
Try it yourself
Goal: read the structure of a project you use, and of your own.
- Open your practice project and look at the full path under its name. Whose namespace is it in?
- Run
git remote -vin your playground and match the URL to that path. - On GitLab, open Your work → Groups. If you belong to none, that is expected for a personal account.
- If you have access to a work project, find its group and look at Manage → Members on the group to see whether access comes from the group or the project.
Expected result: you can state, for one real project, whether your access comes from the group or from the project itself.
Show solution
On the project's Manage → Members page, entries granted through a group show the group's name in the Source column rather than "Direct member". That column is the answer to "why do I have access to this?", and it is the first place to look when someone unexpectedly does or does not.