RFC-99: Upcoming changes to Bitbucket navigation

General Request for Comments (RFC)
, , ,
1

Summary of Project

  • Publish : July 8, 2025
  • Discuss : July 31, 2025
  • Resolve : August 15, 2025

By now you will likely be very familiar with the new navigation system that we’ve already rolled out to Jira and Confluence Cloud with the help of you, our developer ecosystem.

We’ll be bringing that same new navigation system to Bitbucket Cloud in late 2025, and we want you to be ready.

The aims of the new navigation for Bitbucket are as follows:

  • Create a consistent appearance and user experience across all our products, making it smoother to switch between tools.
  • Improve the scalability and expansion of our product features.
  • Include customization options in the navigation, ensuring our system aligns with industry standards and integrates seamlessly with popular tools.

Proposed Solution

atlassian-new-nav-system
atlassian-new-nav-system1280×745 68.2 KB

The key changes in the new navigation are:

  • Simplified top navigation: We’ve reimagined the top navigation, decluttering it to keep the focus on essential tasks like search and create. All other product and navigation items have been relocated to the sidebar for easier access.
    • Product and global navigation: Product-specific navigation and global items, like Apps, are now listed in the left sidebar.
    • Project navigation: Project-specific navigation, like boards, backlogs, and timelines, are restructured as tabs for efficient navigation in a project.
  • Customizable and collapsible sidebar: Customize and collapse sections within the left sidebar to focus on what matters most to you. Personalize your navigation further by showing or hiding the menu items on the sidebar.
  • Unified look and feel: The new navigation is designed for a cohesive experience across all Atlassian products, enabling co-usage between them.
  • Effortless project switching: Get to your work faster with fewer clicks, even when working across multiple projects.

What do these changes mean for Ecosystem developers and partners?

1. Workspace-level apps

Current navigation

Workspace-level apps are accessible under More in the top navigation, and appear at full screen width.

current-workspace-apps
current-workspace-apps2798×1449 151 KB

New navigation

Workspace-level apps will be accessible under Apps in the side navigation, and appear along with collapsible side navigation.

new-workspace-apps
new-workspace-apps2882×1720 116 KB

2. Workspace-level app settings

Current navigation

Workspace-level app settings are accessible under Settings > Workspace settings in the top navigation and appear below other workspace settings, with each app having its own subsection.

current-workspace-app-settings
current-workspace-app-settings2799×1662 260 KB

New navigation

Workspace-level app settings will be accessible under Settings > Workspace settings in the top navigation and appear below other workspace settings, with all apps in a single Apps subsection.

new-workspace-app-settings
new-workspace-app-settings2882×1720 120 KB

3. Repository-level apps

Current navigation

Repository-level apps are accessible below other items in repository left navigation.

current-repository-apps
current-repository-apps1398×789 38.6 KB

New navigation

Repository-level apps will be accessible under Apps in repository left navigation.

new-repository-apps
new-repository-apps2882×1720 145 KB

4. Repository-level app settings

Current navigation

Repository-level app settings are accessible under Settings in repository left navigation and appear below repository settings, with each app having its own subsection.

current-repository-app-settings
current-repository-app-settings1398×807 51 KB

New navigation

Repository-level app settings are accessible under Settings in repository left navigation and appear below repository settings, with all apps in a single Apps subsection.

new-repository-app-settings
new-repository-app-settings2882×1720 127 KB

Feedback

We’d appreciate any reactions you have to this RFC, and we’re especially interested in learning more about:

  1. What impact do you see with your APIs/apps due to the navigation menu items changing with respect to their placements?
  2. How can we help you adopt the new navigation changes with minimal impact?

Rough timeline

  • The timelines below are targets based on our current understanding of the work involved. With that said, they could change.
  • Designs are still evolving, and we will share final designs at a later date via Product Tech Talks, Community posts, and/or webinars.
  • We can enable the new navigation for partners at the beginning of the Early Access Program to provide as much time as possible to plan for any changes to apps.
  • Early Q4 2025 (Oct-Dec): Early Access Program for new navigation begins. This will be the first opportunity for ecosystem partners to test the new navigation.
  • Late Q4 2025 (Oct-Dec): General availability rollout start.
3 Likes
2

Hi @dparrish
Thanks for sharing.
I do have a few questions:

App UX

Folding and hiding apps under a general ‘Apps’ folder:

  • decreases discoverability for users
  • adds an extra click to access app features

:red_question_mark: Can users customise the sidebar and ‘bookmark’ app menu items to escape from being hidden by default?

App menu & (App settings)
The new structure suggests one ‘MyApp’ (settings) menu item under (Settings >) Apps.

  • What happens to apps that have multiple items under settings, both on WS and Repo level? [1]

App DX

Are there any changes (to app module locations) required for the app descriptor?
The timeline above clashes with end of connect timeline.

I would expect that apps with multiple menu items per location in their descriptor should just work?

Missing: Project(/Settings)

Can you please add an app Project/(Settings) proposal?

  1. Could multiple items for one app be treated as ‘container navigation’? ↩︎

4 Likes
3

Thanks for your questions @UlrichKuhnhardtIzym1 !

Re: Folding and hiding apps under a general ‘Apps’ folder
The number of clicks isn’t really a good metric here. Less clicks does not necessarily mean a better user experience, and it’s also not something we’re optimizing for. Grouping all apps under a “apps” menu on the repository page improves organization and therefor also discoverability. The current model of allowing every app to put a page directly in the repository navigation doesn’t scale very well; the experience gets worse the more apps are available for that repository. We’re still working through the details, but there will be some level of customization that a user can do, similar to Jira and Confluence.

Re: App menu & (App settings)
Good question. Ideally, we’d like each app to have one main settings page (as opposed to multiple). Do you see any specific issues or concerns with this approach?

Re: App DX
I don’t have an answer to this question. We’ll get back to you.

Re: Missing: Project(/Settings)
Project settings for apps will work similar to repository and workspace settings.

4

Thanks for the update @markus1

I’m glad to hear Atlassian is open to work through details together with app developers.

Re: App menu & (App settings)

My concern here is: The published connect schema defines these as array.

        "adminPages": {
          "type": "array",
          "description": "Used to show a link and full page within an admin section",
          "items": { ...

Bitbucket forge modules suggest a similar array structure for menu items.

IMHO the schema should be honoured after the proposed nav updates. This is critical for Apps to work.

Re: Missing: Project(/Settings)

I’m not aware of a publisjed project level connect or forge module location.
Connect:

              "location": {
                "type": "string",
                "description": "Location in the application interface.",
                "enum": [
                  "org.bitbucket.account.admin",
                  "org.bitbucket.repository.admin"
                ],

Forge:
Repo main page(s), Repo settings page(s), Workspace settings page(s)

Are project level modules going to be released, or if already supported, are there any resources on how to incorporate them?

1 Like
5

@UlrichKuhnhardtIzym1 We aren’t planning on adding project-level UI extension points at this time.

6

@dparrish Interesting. Because here RFC-86 Bitbucket Connect to Forge: Input on the Migration Process - #9 by EdmundMunday it made the impression that project level UI is finally a priority.

Is there a roadmap of upcoming features and extension points for Bitbucket Cloud?

1 Like
7

@christian.ott @UlrichKuhnhardtIzym1 Apologies, I should have been more clear! In the context of rolling out new navigation, we aren’t specifically contemplating a project-level extension point. However, assuming we add a project-level extension point as part of the Connect-to-Forge migration process, we’ll of course make that available in the new navigation system.

It mostly comes down to sequencing! I am conferring with my colleagues on the Connect-to-Forge team to clarify whether we want to add a project touchpoint before or after migration to the new nav.

1 Like
8

Thanks @dparrish that’s great news! We would like app project settings very much for the same reasons Bitbucket has introduced them a while back.

I would also much appreciate a comment on your plans to accommodate an array of app menu items in current schema locations with the suggested new navigation.

Thanks for staying in touch!

1 Like
9

@UlrichKuhnhardtIzym1 :+1: Acknowledging your question about the array of menu items, which makes complete sense. I’m discussing with design and we will get back to you with an answer.

10

@dparrish I’m not sure this statement is accurate - there is a General Page module for Connect however that does not currently work and as such I don’t believe there are any Bitbucket Cloud apps which include workspace-level pages in the “More” dropdown as you’ve described. There is a feature request here to add support for General Pages to Forge, however at the time of writing this has not been implemented.

Could you please confirm whether my understanding is correct? And if so, whether support for General Pages (aka “Workspace-level apps”) in Forge/Connect is being added as part of the rollout of the new navigation here? Thanks!

11

A Connect app can currently use the Profile tab module to place its item into the More menu on the workspace level. So, actually, you can integrate your app there in Connect, but not in Forge (yet).

1 Like
12

Thanks very much @aokulovich - just verified that is correct.

Extremely confusing because the documentation for that module says:

Module for pages on the profile page.

which I thought was referring to the public user profile page which is available in Bitbucket Server and Data Center (and formerly in Bitbucket Cloud)

Whereas the documentation for General Page says:

Allows an app to insert new pages into Atlassian products with no extra styling. By default a link to the page is displayed in the main navigation menu.

which seems to actually be what Profile Tab does.

I look forward to this hopefully being resolved in a new Forge module :folded_hands:

1 Like