Mastering GitLab: How to Create a Subgroup in GitLab

GitLab is a powerful platform for managing and collaborating on software projects. One of its key features is the ability to create groups and subgroups, which can help organize related projects and streamline access control. This article will guide you through the process of creating a subgroup in GitLab, providing detailed steps and practical examples to help you master this essential feature.

Table of Contents

Key Takeaways

  • GitLab groups allow you to manage multiple related projects and their permissions in one place.
  • Subgroups can be created within existing groups to further organize projects and teams.
  • Creating a group involves selecting a name, URL, and visibility level, and then adding members.
  • Namespaces in GitLab are unique names used for users, groups, or subgroups, helping in organizing and accessing projects.
  • Effective management of groups and subgroups can enhance collaboration and simplify project management.

Understanding GitLab Groups and Subgroups

team collaborating on a project with GitLab interface on screen

Definition of GitLab Groups

In GitLab, groups are used to manage one or more related projects simultaneously. Groups can assemble related projects together and grant members access to several projects at once. Each project within a group has its own repository, issues, merge requests, and more. Groups can also be nested into subgroups, allowing for even more organized project management.

Benefits of Using Groups and Subgroups

Using groups and subgroups in GitLab offers several advantages:

  • Centralized Access Control: If someone has access to the group, they get access to all the projects in the group.
  • Simplified Project Management: You can view all issues and merge requests for the projects in the group.
  • Enhanced Collaboration: Easier to @mention team members and manage permissions.
  • Analytics: View analytics that shows the group’s activity.

Common Use Cases for Groups and Subgroups

Groups and subgroups are commonly used to:

  • Organize related projects under the same namespace.
  • Add members to the groups and grant permissions all at once.
  • Create a group for a company and subgroups for different teams, such as frontend-team and backend-team.

Creating groups and subgroups makes communication easier in GitLab. For example, you can invite multiple projects to a group, sometimes called sharing a project with a group.


  • (Amir’s GitLab Profile)
  • (Amir creates his group)
  • (Subgroup named sales)

Navigating to the Group Creation Page

Accessing the GitLab Menu

To start creating a group in GitLab, you first need to access the main menu. Navigate to the top-left corner of your GitLab interface and click on the Menu icon. This will open a dropdown list of options available to you.

Locating the Groups Section

Once the menu is open, look for the ‘Groups’ section. This is where you can manage all your groups and subgroups. Click on ‘Groups’ to proceed to the next step.

Initiating Group Creation

In the ‘Groups’ section, you will see a plus sign (+) to the left of the search box. Click on this plus sign and then select ‘New group’. This will take you to the group creation page where you can start setting up your new group. Be mindful that some group names are reserved and cannot be used. After entering the group name, provide a unique path for your group in the Group URL field. Finally, choose a visibility level for your group: public, internal, or private.

Steps to Create a New Group in GitLab

Selecting ‘Create Group’ Option

To create a group in GitLab, you need to navigate through the menu. Select Menu > Groups > Create group. Then, to the left of the search box, click the plus sign and select ‘New group’. This will initiate the group creation process.

Entering Group Name and URL

Once you have initiated the group creation, you will need to enter a group name. Be mindful that some group names might conflict with existing routes used by GitLab, so there are reserved names you cannot use. Next, enter a path for your group in the Group URL. This URL is used for the namespace, which is a unique name for a user, group, or subgroup.

Choosing Visibility Level

After setting the group name and URL, you will need to choose a visibility level for your group. The options are:

  • Public: Accessible by anyone.
  • Internal: Accessible by any logged-in user.
  • Private: Only accessible by members you invite.

Personalize the group by defining your role, who will be using the group, and what the group will be used for. Finally, invite all relevant GitLab members to join the group.

Creating a group in GitLab allows you to manage multiple projects simultaneously and streamline permissions. This ensures that anyone with access to the GitLab group will have access to all projects within that group.

Creating a Subgroup within an Existing Group

Accessing the Parent Group

To create a subgroup, you first need to navigate to the parent group where you want the subgroup to reside. This can be done by selecting the parent group from your GitLab dashboard. Ensure you have the necessary permissions to create subgroups within this parent group.

Initiating Subgroup Creation

Once inside the parent group, locate the ‘New Subgroup’ button, usually found in the group’s main menu. Clicking this will initiate the subgroup creation process. This feature is available in GitLab Premium, providing advanced options for subgroup management.

Configuring Subgroup Settings

After initiating the creation process, you’ll need to configure the settings for your new subgroup. This includes:

  1. Entering a Subgroup Name and URL: Choose a unique name and URL for your subgroup. The URL will serve as the namespace for the subgroup.
  2. Choosing Visibility Level: Decide whether the subgroup will be public, internal, or private. This setting can be adjusted later if needed.
  3. Adding Members: You can add members directly to the subgroup or inherit members from the parent group. This makes it easier to manage users across multiple groups.

Creating subgroups within a parent group helps in organizing projects and teams more efficiently, especially in large organizations. It simplifies user management and enhances collaboration.

By following these steps, you can effectively create and manage subgroups within your GitLab environment, leveraging the full potential of GitLab Premium.

Managing Members in Your GitLab Group

Adding Members to a Group

To add members to your group, navigate to your group page and click on the ‘Members’ tab. Here, you can invite users by entering their username or email address. You can also set their role within the group, such as Developer or Maintainer. Adding members to a group ensures they have access to all projects within that group.

Assigning Roles and Permissions

Roles in GitLab are crucial for managing what each member can do within the group. The available roles include Guest, Reporter, Developer, Maintainer, and Owner. Each role comes with specific permissions:

Role Permissions
Guest Can view issues and merge requests
Reporter Can view and create issues, and leave comments
Developer Can push to branches, create merge requests, and manage issues
Maintainer Can manage the repository, including protected branches and settings
Owner Has all permissions, including managing members and group settings

Removing Members from a Group

If you need to remove a member from your group, go to the ‘Members’ tab, find the user you wish to remove, and click the ‘Remove’ button next to their name. This action will revoke their access to all projects within the group.

Properly managing members and their roles is essential for maintaining a secure and efficient workflow in GitLab.

Utilizing Namespaces in GitLab

Understanding Namespaces

In GitLab, a namespace is a unique name used as a username, group name, or subgroup name. This unique identifier helps in organizing and managing projects efficiently. Namespaces ensure that there are no conflicts between different entities within GitLab, making it easier to locate and manage resources.

Creating Unique Namespaces

To create a unique namespace in GitLab, follow these steps:

  1. Navigate to the Menu and select ‘Groups’.
  2. Click on ‘Create group’ and enter a group name.
  3. Provide a unique path for your group in the Group URL field. This path will serve as the namespace.

Be mindful that some names are reserved and cannot be used as namespaces. Always check for availability before finalizing the name.

Best Practices for Namespace Management

Managing namespaces effectively can streamline your workflow. Here are some best practices:

  • Use descriptive names that clearly indicate the purpose or ownership of the group or project.
  • Avoid using special characters or spaces in the namespace.
  • Regularly review and update namespaces to reflect any organizational changes.

Proper namespace management is crucial for maintaining an organized and efficient GitLab environment. It helps in avoiding conflicts and ensures smooth collaboration among team members.

Practical Examples of Group and Subgroup Structures

Company and Team Structures

Organizing your GitLab groups to reflect your company’s structure can significantly enhance collaboration and project management. For instance, you can create a main group for your company and subgroups for each department or team. This hierarchical structure simplifies communication and access control.


  • Company-Group
    • Engineering-Team
    • Marketing-Team
    • Sales-Team

Project-Based Grouping

Another effective way to organize your GitLab groups is by project. This is particularly useful for companies that handle multiple projects simultaneously. Each project can have its own group, with subgroups for different aspects of the project, such as development, testing, and documentation.


  • Project-Alpha
    • Development-Team
    • Testing-Team
    • Documentation-Team

Namespace Examples

In GitLab, a namespace is a unique name used for a user, group, or subgroup. Proper namespace management ensures that your groups and subgroups are easily identifiable and accessible. For example, a namespace for a user might look like, while a group namespace could be

Properly structured namespaces make it easier to manage permissions and access across different projects and teams.



Benefits of Organizing Projects in Groups

Simplified Project Management

Organizing projects into groups in GitLab significantly simplifies project management. By grouping related projects together, you can manage permissions, settings, and access controls more efficiently. This is particularly useful in large organizations where multiple teams work on interconnected projects. Instead of managing each project individually, you can apply changes at the group level, saving time and reducing the risk of errors.

Enhanced Collaboration

Groups in GitLab foster enhanced collaboration among team members. When projects are organized into groups, it becomes easier for team members to find and contribute to relevant projects. This is especially beneficial for cross-functional teams working on shared goals. Additionally, using features like @mentions within groups can streamline communication and ensure that the right people are notified about important updates.

Centralized Access Control

One of the key benefits of using groups in GitLab is centralized access control. With groups, you can grant or revoke access to multiple projects with a single action. For instance, if a new developer joins your team, you can add them to the relevant group, and they will automatically gain access to all projects within that group. This centralized approach not only saves time but also ensures consistent access permissions across projects.

In GitLab Ultimate, you can leverage advanced group management features to further streamline your project organization and access control.

By organizing projects into groups, you can achieve a more structured and efficient workflow, ultimately leading to better project outcomes and a more cohesive team environment.

Advanced Tips for Group and Subgroup Management

Using @mentions Effectively

One of the most powerful features in GitLab is the ability to use @mentions to quickly notify team members. Using @mentions effectively can streamline communication and ensure that the right people are alerted to important updates. For example, you can mention a whole team by using @<group-name>/<subgroup-name>, such as @team/frontend-team.

Monitoring Group Activity

Keeping an eye on group activity is crucial for maintaining productivity and security. GitLab provides various tools to monitor activities, such as the Activity tab, which shows recent changes and updates. Regularly reviewing this can help you catch issues early and keep everyone on the same page.

Optimizing Group Settings

Configuring your group settings properly can save you a lot of headaches down the line. Make sure to set appropriate permissions and roles for each group and subgroup. This not only enhances security but also makes it easier to manage users. For instance, you can assign different roles like Owner, Maintainer, and Reporter to different members, ensuring that everyone has the right level of access.

Properly managing your GitLab groups and subgroups can significantly improve your workflow and collaboration efforts. Take the time to set them up correctly, and you’ll reap the benefits in the long run.

Common Issues and Troubleshooting

Resolving Group Creation Errors

Creating a group in GitLab can sometimes lead to unexpected errors. One common issue is the lack of necessary permissions. Ensure that you have the appropriate access level to create a group. If you encounter an error, double-check the group name and URL for any invalid characters.

Handling Permission Issues

Permission issues can arise when managing groups and subgroups. It’s crucial to understand the different roles and their permissions. If a member cannot access certain features, verify their assigned role. You can adjust roles by navigating to the group’s settings and updating the member’s permissions accordingly.

Best Practices for Group Maintenance

Maintaining your GitLab groups effectively requires regular audits and updates. Periodically review group members and their roles to ensure they align with current project needs. Additionally, keep an eye on group activity to identify any unusual behavior or potential security risks.

Regular maintenance and monitoring can prevent many common issues and ensure smooth workflows for working with community contributions.


Mastering GitLab and understanding how to create and manage subgroups can significantly streamline your project management and collaboration efforts. By organizing related projects under a unified namespace and leveraging the power of groups and subgroups, you can enhance communication, simplify permissions, and improve overall productivity. Whether you’re managing a small team or a large organization, GitLab’s subgroup feature offers a flexible and efficient way to keep your projects and teams well-coordinated. Start implementing these practices today to make the most out of your GitLab experience.

Frequently Asked Questions

What are GitLab groups and subgroups?

GitLab groups are used to manage one or more related projects simultaneously. Subgroups are nested groups within a primary group, allowing for even finer organization.

How do I create a new group in GitLab?

To create a group in GitLab, navigate to Menu > Groups > Create group. Enter a group name, URL, and choose the visibility level.

What are the benefits of using groups and subgroups in GitLab?

Using groups and subgroups helps in organizing related projects under the same namespace, simplifying project management, enhancing collaboration, and centralizing access control.

How can I create a subgroup within an existing group?

To create a subgroup, access the parent group, initiate subgroup creation, and configure the subgroup settings.

How do I manage members in a GitLab group?

You can manage members by adding them to the group, assigning roles and permissions, and removing members when necessary.

What is a namespace in GitLab?

In GitLab, a namespace is a unique name used as a username, group name, or subgroup name. It helps in organizing and managing projects effectively.

Can I view all issues and merge requests for projects in a group?

Yes, you can view all issues and merge requests for all projects within a group, as well as access analytics for all activities within the group.

What should I do if I encounter issues while creating a group?

If you encounter issues while creating a group, ensure that the group name does not conflict with reserved names and check your permissions. Refer to GitLab’s troubleshooting guide for more help.

You may also like...