Managing Portfolios

Portfolios are available starting in Enterprise Edition.

Permissions

There are two levels of users with permissions for adding and editing Portfolios: users with the Create Portfolios permission and Global Administrators.

Create Portfolios Permission

Users with the Create Portfolios permission (granted at the global level at Administration > Security > Global Permissions) can create Portfolios by clicking the "+" in the top menu.

Create Portfolios

Users with the Create Portfolios permission can edit an individual Portfolio definition from the Portfolio-level Portfolio Settings > Edit Definition interface.

Global Administrators

In addition to the access granted to users with the Create Portfolios permission, Global Administrators have access to the overall Portfolio and Application administration interface at Administration > Configuration > Portfolios. From this page, they can create and edit Portfolios.

Global Administrators also have access to the Projects Management page at Administration > Projects > Management. Changing the selection mechanism on this page to “Portfolios” or “Applications” lets you manage the Portfolios or Applications of your SonarQube instance. The dropdown menu to the right of each item lets you edit permissions, apply Permission Templates or restore access to a Portfolio or Application.

Populating Portfolios

Once your Portfolio exists, you can populate it with any mix of projects, Applications, and sub-portfolios.

Adding a Sub-portfolio

To add a sub-portfolio, click on “Add Portfolio” at the top of the third column, and choose:

  • Standard - This option allows you to create a new sub-Portfolio from scratch. Once created, you can add projects, applications, and more layers of sub-portfolios.
  • Local Reference - This option allows you to reference an existing Portfolio/Application as a sub-portfolio. Once added, it is not editable here, but must be chosen in the left-most column to be edited.

Adding Projects to a Portfolio

To add projects directly to a Portfolio or standard sub-Portfolio first make sure the correct item is selected, then choose the Project selection mode:

  • Manual – choose the projects individually.
  • Tags - select one or more project tags. Projects with those tags will automatically be included.
  • Regular Expression – specify a regular expression and projects with a matching name OR key will be included.
  • All Remaining Projects – choose this option to add all projects not already included in this Portfolio (directly or via sub-Portfolio).

Adding Applications to a Portfolio

To add an Application to a Portfolio, first make sure your Application is already created. Then:

  1. Navigate to the Portfolios configuration page by going to Administration > Configuration > Portfolios.
  2. Select the Portfolio where you want to add your Application
  3. Click Add Portfolio
  4. Select Local Reference
  5. Choose your Application from the drop-down list and click Add.

Project unicity under a portfolio

Projects, applications and sub-portfolios can only appear once in any given hierarchy in order to avoid magnifying their impacts on aggregated ratings. The portfolio configuration interface has some logic to prevent obvious duplications (e.g. manually adding the same project), however in case of more subtle duplications (e.g. due to regex, or other bulk definition), then the calculation of that portfolio will fail with a helpful error message.

Calculation

By default, Portfolios are queued to be recalculated after each analysis of an included project. For each relevant Portfolio, a “Background Task” is created, and you can follow the progress on each in the Administration > Projects > Background Tasks by looking at the logs available for each item.

If you're having performance issues related to automatic recalculation of large portfolios, you can specify the hour(s) at which you want them to be recalculated at Administration > Portfolios > Recalculation. Portfolios are queued to be recalculated at the beginning of the hour(s) that you specify.

Reindexing

During Elasticsearch reindexing due to disaster recovery or an upgrade, you won't have access to Portfolios until all projects are indexed.