Best practices to set up organizational hierarchies that scale

Maximizing the benefits of your GitLab subscription begins with an effective organizational setup. Here’s a straightforward guide to configuring your group, subgroup, and project structure to enhance your GitLab experience.

Understanding the structure: Groups, subgroups, and projects

Groups and projects allow you to model your organizational hierarchy, enabling advanced permissions management and “team of teams” planning. Use groups and subgroups for strategic planning and configuration management that cascades into subgroups and projects lower in the hierarchy.

Beyond this, you can also model your value streams, enhancing project management and collaboration across your organization.

• Project level (team level)

  • Nested within groups or subgroups, projects are where your actual work happens. This is where repositories live, and settings specific to the project are managed. Zoom into day-to-day activities and detailed project tracking at this level.
  • Effective project configuration helps maintain clean, organized data, which is essential for accurate reporting and analysis.

• Subgroup level (team of teams)

  • Subgroups provide granular permissions management and can be tailored to specific team or project needs, ensuring consistent workflows across your organization.
  • Subgroups function as clusters of related projects, similar to how a "team of teams" operates in Agile.
  • This level is ideal for managing several teams working towards a common product or service. It facilitates cross-project visibility and integration, which supports synchronization between teams to align on interdependencies and shared objectives.

• Group level (team of team of teams)

  • Think of groups as your organizational pillars within GitLab where broad permissions and access are managed.
  • At the highest level, groups encompass multiple subgroups and represent the strategic tier of project management, akin to the "team of team of teams" in Agile.
  • This level sets the overarching goals and strategies, defining settings and allocating resources across projects and subgroups to ensure alignment with the company's broad business objectives.

By structuring your organization with GitLab, you parallel your chosen Agile methodology, which can help you apply Agile principles more naturally across your projects. This structure promotes clear lines of communication, efficient resource management, and strategic alignment, all while maintaining the flexibility and responsiveness inherent to Agile methodologies.

Keep up with news and insights about GitLab Agile planning.

Leveraging the GitLab inheritance model

One of GitLab's powerful features is its inheritance model, which allows settings, permissions, and configurations made at higher levels to automatically apply to lower levels within the hierarchy. Conversely, data at lower levels is instinctively available at higher levels in the structure. With the inheritance model, you gain visibility across your entire portfolio from within higher-level groups while providing distinct locations lower in the hierarchy for individual teams to manage their work.

Examples:

• Create milestones and labels in your higher-level groups to cascade down to all subgroups and projects promoting consistency and adherence to organizational standards.
• Issues and epics in lower level projects and subgroups roll up your value stream hierarchy for ease of reference by program management and the executive layer.
• Manage user permissions at the group level or top-level subgroup to optimize permissions and access control. This can simplify access control management and ensure that the right people have the right access across multiple projects without the need for repeated configuration.

These tips not only streamline administrative overhead but also reinforce security and compliance by ensuring that changes at the higher level consistently propagate downwards.

Best practices for GitLab setup

When setting up your GitLab organizational hierarchy, we recommend the following options depending on your organization's needs. Self-managed customers have the option to omit the "Company Name" root group layer, as this extra level of organization is not necessary for self-managed deployments. This flexibility ensures that your GitLab setup is tailored to your specific organizational structure and deployment preferences.

Option 1: Permissions and access are granted at the organizational subgroup level

This option is ideal for complex permission structures or large organizations needing efficient project sharing across numerous users.

Example structure

• Organizational Group

  • Handles broad permissions typically through integrations with corporate provisioning systems.
  • Users are added to subgroups, which will serve as the foundation for sharing the entire group with another group or a project to minimize the overhead of direct user management.
  • When creating user groups, you can utilize group mentions throughout GitLab to mention large groups of users at a time.

• Development Group

  • Provides executive-level and program-management-level visibility across all development projects at the highest development group level.
  • Features are created at the subgroup level for access across multiple repos.
  • Projects are created to hold development repos; this is the level for Team visibility.

Option 2: Permissions and access are granted at any level

This option is best for smaller organizations with less complex access requirements. Users are added individually to the divisional groups, subgroups, or projects as access is required. This provides direct control over project management and operational visibility.

Highlights

• Users can be added to a group at the top of the hierarchy or to the lower-level subgroup/project depending on the granularity of access needs. Each member would need to be individually added rather than a single task of sharing a group.
• Executive-level and program-management-level visibility across all development projects at the highest development group level.
• Features are created at the subgroup level for access across multiple repos.
• Projects are created to hold development repos; this is the level for Team visibility.

Additional configuration considerations

• Milestones and iterations

  • Create group-level milestones for broad visibility or when milestones need to be shared across groups.
  • Create milestones at the project level when the milestone is specific to a single project.
  • For teams working across different groups, setting iterations at the parent group level is beneficial for unified tracking.

• Data management

  • Leverage GitLab's roadmaps, boards, and listing pages to pull data that reflects your organizational setup. This helps you visualize progress and plan effectively across different levels of your structure.
  • GitLab makes data available in higher-level groups even when the data is created in lower levels.
  • Create your views at higher levels when you want to view data across groups and projects, and at lower levels when you want to hone in on a specific group or project’s data.

• Template creation

  • Create higher-level templates to ensure they cascade to all subsequent subgroups and projects, mixing general guidelines with project-specific requirements.
  • Templates are created within their own repository within the applicable group (related documentation).

• Labels

  • Create higher-level labels to ensure they cascade to all subsequent subgroups and projects, mixing org labels with project-specific labels.
  • Use scoped labels to define organizational structures like teams and workflow status.

Leveraging GitLab’s features for optimal performance

Implementing the right structure in GitLab not only streamlines the management of your software projects but also enhances the visibility across different levels of your organization, ensuring that everyone from the top management to individual contributors has the information they need to make informed decisions.

Get started modeling organizational hierarchy with a free 30-day trial of GitLab Ultimate.