Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Groups, Projects and Namespaces

Organize work in GitLab with groups, subgroups and projects: namespaces, visibility levels, member roles, inheritance, and how to create your first project.

A GitLab project holds one repository together with its issues, merge requests, pipelines, wiki and settings. A group collects projects and people so that permissions and settings can be managed in one place. Getting this structure right early saves painful migrations later, because moving projects around changes their URLs.

Namespaces: where things live

Every project lives in a namespace, which is either your personal namespace (gitlab.com/ada) or a group (gitlab.com/acme). A namespace can contain more than projects: a group can contain subgroups, nested up to many levels deep.

flowchart TD
  G["acme (group)"] --> S1["web (subgroup)"]
  G --> S2["platform (subgroup)"]
  S1 --> P1["storefront (project)"]
  S1 --> P2["admin-panel (project)"]
  S2 --> P3["ci-templates (project)"]
  G --> P4["handbook (project)"]

The full path of the first project is acme/web/storefront.

Use personal namespaces for experiments and learning, and groups for anything a team owns. A project in a group survives when a person leaves; a project in a personal namespace belongs to that person.

Creating a group and a project

To create a group, open the Groups area from the sidebar and choose New group. You supply a name, a URL slug (the path), and a visibility level. A subgroup is created from inside a parent group with New subgroup.

To create a project, choose New project and pick one of:

  • Create blank project: an empty repository. Choose the namespace, the project name, the visibility, and whether to initialize with a README. Initializing creates the first commit on main.
  • Create from template: starter projects for common frameworks that already contain a .gitlab-ci.yml.
  • Import project: bring a repository from another host (GitHub, Bitbucket and others) along with issues where supported.

If you created an empty project, GitLab shows you the exact commands to push existing code. They look like this:

Terminal
git remote add origin [email protected]:acme/web/storefront.git
git branch -M main
git push -u origin main

You need an SSH key or token set up first.

Visibility levels

Both groups and projects have a visibility level.

  • Private: only members can see it.
  • Internal: any signed-in user on the instance can see it (not available on GitLab.com for new items in most setups; common on self-managed servers).
  • Public: anyone on the internet can see it, even without logging in.

A project cannot be more visible than its group. If the group is private, every project inside it is private too. The stand-in below captures this rule so you can see how a request for a wider level is capped.

Python Stand-in: visibility can never exceed the parent

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Member roles and permissions

People get access by being added as members with a role. The roles, from least to most powerful, are:

  1. Guest: view and comment on issues in private projects, but limited access to code.
  2. Planner: manage planning items such as issues and epics without code access (available in current versions).
  3. Reporter: read the repository, download artifacts, manage issues; cannot push code.
  4. Developer: push to unprotected branches, create merge requests, run pipelines.
  5. Maintainer: manage protected branches, project settings, runners and merge into protected branches.
  6. Owner: everything, including deleting the group or changing its visibility.

Members of a group inherit their role in every project below it. If Ada is a Developer in acme, she is a Developer in acme/web/storefront unless you give her a higher role there. You can raise a role on a lower level but not reduce it below what was inherited.

Here is a small stand-in for the permission ladder. The table of minimum roles is a simplified model of the most common defaults, not the full permission table.

Python Stand-in: who may do what (simplified)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the last lines: a direct Reporter role does not lower an inherited Developer role.

Group features you will use

  • Shared settings: CI/CD variables, runners and access tokens defined on a group apply to all its projects (see variables and rules and runners).
  • Group-wide views: issue lists, merge request lists and boards that span many projects.
  • Sharing: a project can be shared with another group, giving that group's members a role on it.
  • Epics and roadmaps (paid tiers): plan work across projects.
  • Transfer: a project can be moved to another namespace by an Owner or Maintainer with rights in the target. GitLab keeps redirects for the old URL for a while, but do not rely on them forever; update remotes with git remote set-url origin NEW_URL.

Naming and structure advice

  • Prefer a few groups with subgroups over many top-level groups. You inherit permissions down the tree.
  • Use short, lowercase, hyphenated project slugs. They become part of every clone URL.
  • Group by ownership (a team), not by technology. Teams change less often than tools.
  • Keep shared CI templates in one project that others can include (see includes and reuse).
  • Give people the lowest role that does the job, and use groups to avoid adding the same people to ten projects individually.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which is the full path of project storefront inside subgroup web of group acme?

    Paths go from the outermost group to the project, separated by slashes.
  2. 2. A private group contains a project you set to public. What is the effective visibility?

    A project can never be more visible than its parent group.
  3. 3. Ada is a Developer in the group. In one project you set her as Reporter. Which role applies there?

    Direct membership can raise but not lower the role inherited from the group.
  4. 4. Which role is the lowest that can merge into a protected branch by default?

    By default only Maintainers may merge into protected branches such as main; you can change that in the branch protection settings.

Summary

  • Projects live in namespaces: a personal namespace or a group, optionally nested in subgroups.
  • Visibility is private, internal or public, and a child cannot exceed its parent.
  • Roles are Guest, Planner, Reporter, Developer, Maintainer and Owner, inherited downward.
  • Groups centralize members, settings, variables and runners.
  • Moving a project changes its URL, so plan the structure early.

Next: SSH Keys and Access Tokens