Portfolio hierarchies are generally available in the SonarQube Cloud for Enterprise plan customers.
You can create and manage parent and child portfolios visually, alongside API-based creation and editing of portfolios for those who prefer automated configuration. This release adds the UI experience and also has an API configuration component to enhance any automation based portfolio creation.
Here’s what you can do and how to get started:
Organize portfolios around your teams and services
A flat list of portfolios can make it difficult to see how teams, services, and projects relate to one another. Hierarchies let you represent those relationships with parent and child portfolios.
For example, Engineering → Platform → Developer Experience places a team within its broader engineering organization. You can navigate between these levels and configure project selection for the portfolio you have selected.
The hierarchy tree shows the relationship between Engineering, Platform, and Developer Experience.
Create a hierarchy
Start from Portfolios, select your enterprise, and choose Create portfolio.
-
In step 1: Enter the portfolio details, then choose Save and continue.
-
In Step 2: Add projects, choose Create child portfolio. Enter its name and, optionally, a description.
-
Select a child in the tree before creating another child beneath it. For example, select Platform to create Developer Experience within Platform.
-
Select the portfolio whose project selection you want to configure, then choose Add projects.
Each portfolio has its own project selection. Check the selected portfolio’s name before adding projects so that you configure the intended level.
Creating a portfolio from the portfolio creation page.
Select the projects you want to add to your designated portfolio.
Create child portfolios and configure project selection during the Add projects step.
Changes made during the creation wizard are saved to the draft as you work. Continue through permissions and review, then choose Complete to make the portfolio live. Saving a draft and completing the portfolio are separate steps.
Update an existing hierarchy
Open the portfolio, then go to Administration → Portfolio definition → Manage portfolio contents.
Use the tree to select a portfolio and inspect its contents. Ancestor links also let you navigate back to higher levels.
The Portfolio actions menu provides actions to edit a child portfolio’s name and description, move it, or delete it. Moving a portfolio changes its position within the tree together with its nested contents. A portfolio cannot be moved into one of its own descendants in the same tree.
Review deletion carefully: deleting a portfolio also deletes its nested child portfolios and their corresponding historical data. Move any children you want to retain before deleting their parent portfolio.
When editing an existing portfolio, use the page-level Save button to apply pending changes. Cancel discards unsaved changes. This differs from the draft-saving behavior in the creation wizard.
Create and manage hierarchies through the API
You can also configure portfolio hierarchies programmatically. The API supports creating parent and child portfolios, retrieving a hierarchy, and updating its structure and project selections.
For example, a script can create Engineering → Platform → Developer Experience, then configure which projects belong directly to each portfolio. Each portfolio has its own project selection; nesting a portfolio establishes its relationship to its parent.
You can also move a portfolio and its nested contents to another location within the same hierarchy, or delete a portfolio and its descendants. The same structural restrictions apply: a portfolio cannot become its own descendant. Deletion also removes the affected portfolios’ historical data.
API configuration is useful for repeatable setup or maintaining a hierarchy from information your organization manages elsewhere. Your integration must explicitly create and update the structure; it does not automatically synchronize your organization chart.
For further information about creating and managing hierarchies via the API, see the SonarQube Cloud API documentation for request formats, authentication, and operation-specific permissions.
Access and feedback
Creating portfolios requires the enterprise Create Portfolios permission. Editing an existing portfolio definition requires Edit permission. See the portfolio administration and permissions documentation for details.
Does this hierarchy structure reflect how your engineering teams and services are organized?
To help us improve, share an example in the replies, including where the structure fits and where you encounter difficulties.