GitLab Navigation

1. You are here:
2. Handbook
3. Product Handbook
4. UX Department
5. GitLab Navigation

On this page

• What is navigation
• When to consider making a change to the navigation
• How to propose a change that impacts navigation
  • Utilizing feature flags

The group::foundations team owns the navigation structures of the GitLab product. Please review this information if you plan to propose changes to GitLab navigation.

Note: a Code Owners approval rule is in place to prevent unapproved changes to the navigation. If you have not followed this process, your Merge Request will be blocked.

What is navigation

Navigation refers to elements that aid users in moving around GitLab, which includes their organization and wayfinding clues. The navigation experience directly impacts the usability and discoverability of our features.

Listed in Pajamas are the elements that impact navigation.

When to consider making a change to the navigation

New additions are very deliberate and are made to optimize user workflows. Proposals should include a business case or data that supports it as key/foundational functionality within GitLab.

We do not add new items in order to:

• Improve discoverability of new features. Instead, look for other opportunities to highlight the functionality throughout the product.
• Optimize for the potential future. We should be forward thinking without over optimizing. As features are developed and added, we can look into what changes may need to occur to support a growing feature.

How to propose a change that impacts navigation

Note: We are not considering any top-level navigation changes to the Project or Group sidebar until 6 months after our new navigation launches (2024-01-11).

1. Before opening an issue, review the elements and patterns for navigation in Pajamas. It is worth checking the direction page to see how your proposal aligns or conflicts with upcoming changes.
2. It is recommended to propose a navigation change 2 milestones ahead of when you want to release. This allows enough time for collaboration between the team requesting navigation changes and Product/UX counterparts in Foundations.
3. If you are ready to propose a navigation change, use this issue template to kick off a discussion with the group::foundations team.
4. The Product Manager for Foundations must approve any proposal as the DRI. They will consult with UX counterparts to consider the impact on the user experience based on user research and business needs. UX and Product Management leadership may also be engaged for feedback when necessary. Turnaround time from Foundations team will be 1 milestone.
5. When you have approval and are ready to start implementation, then follow the GitLab Docs on adding items to the navigation.

Utilizing feature flags

Feature flags are a great way for teams to merge changes in smaller batches without negatively impacting the user experience.

When shipping navigation changes behind a feature flag, it is required to present a proposal that considers the future state with a clear, validated vision of the final outcome. We do not merge iterative navigation changes behind a feature flag without having an understanding of the end state.