Skip to content

Analytics dashboards

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Version history

  • Introduced in GitLab 15.9 as an experiment feature with a flag named combined_analytics_dashboards. Disabled by default.
  • combined_analytics_dashboards enabled by default in GitLab 16.11.
  • combined_analytics_dashboards removed in GitLab 17.1.
  • filters configuration introduced in GitLab 17.9. Disabled by default.
  • Inline visualizations configuration introduced in GitLab 17.9.

Analytics dashboards help you visualize collected data. You can use built-in dashboards by GitLab or create your own custom dashboards.

Data sources

Version history

  • Product analytics and custom visualization data sources removed in GitLab 17.7.

A data source is a connection to a database or collection of data which can be used by your dashboard filters and visualizations to query and retrieve results.

Built-in dashboards

To help you get started with analytics, GitLab provides built-in dashboards with predefined visualizations. These dashboards are labeled By GitLab. You cannot edit the built-in dashboards, but you can create custom dashboards with a similar style.

The following built-in dashboards are available:

  • Value Streams Dashboard displays metrics related to DevOps performance, security exposure, and workstream optimization.
  • AI Impact Dashboard displays the impact of AI tools on software development lifecycle (SDLC) metrics for a project or group.

Custom dashboards

You can create custom dashboards to visualize the metrics that are most relevant to your case.

  • Each project can have an unlimited number of dashboards. The only limitation might be the repository size limit.
  • Each dashboard can reference one or more visualizations.
  • Visualizations can be shared across dashboards.

Project maintainers can enforce approval rules on dashboard changes with features such as code owners and approval rules. Your dashboard files are versioned in source control with the rest of a project's code.

View project dashboards

Prerequisites:

  • You must have at least the Reporter role for the project.

To view a list of dashboards (both built-in and custom) for a project:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Analyze > Analytics dashboards.
  3. From the list of available dashboards, select the dashboard you want to view.

View group dashboards

Version history

Prerequisites:

  • You must have at least the Reporter role for the group.

To view a list of dashboards (both built-in and custom) for a group:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Analyze > Analytics dashboards.
  3. From the list of available dashboards, select the dashboard you want to view.

Change the location of dashboards

You can change the location of your project or group custom dashboards.

Prerequisites:

  • You must have at least the Maintainer role for the project or group the project belongs to.

Group dashboards

Issue 411572 proposes connecting this feature to group-level dashboards.

To change the location of a group's custom dashboards:

  1. On the left sidebar, select Search or go to and find the project you want to store your dashboard files in. The project must belong to the group for which you create the dashboards.
  2. On the left sidebar, select Search or go to and find your group.
  3. Select Settings > Analytics.
  4. In the Analytics Dashboards section, select your dashboard files project.
  5. Select Save changes.

Project dashboards

By default custom dashboards are saved to the current project, because dashboards are usually defined in the project where the analytics data is retrieved from. However, you can also have a separate project for dashboards. This setup is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects.

You can share dashboards only between projects that are located in the same group.

To change the location of project dashboards:

  1. On the left sidebar, select Search or go to and find your project, or select Create new ({plus}) and New project/repository to create the project to store your dashboard files.
  2. On the left sidebar, select Search or go to and find the analytics project.
  3. Select Settings > Analytics.
  4. In the Analytics Dashboards section, select your dashboard files project.
  5. Select Save changes.

Create a dashboard by configuration

You can create dashboards manually by configuration.

To define a dashboard:

  1. In .gitlab/analytics/dashboards/, create a directory named like the dashboard.

    Each dashboard should have its own directory.

  2. In the new directory, create a .yaml file with the same name as the directory, for example .gitlab/analytics/dashboards/my_dashboard/my_dashboard.yaml.

    This file contains the dashboard definition. It must conform to the JSON schema defined in ee/app/validators/json_schemas/analytics_dashboard.json.

  3. Optional. To create new visualizations to add to your dashboard, see defining a chart visualization template.

For example, if you want to create three dashboards (Conversion funnels, Demographic breakdown, and North star metrics) and one visualization (line chart) that applies to all dashboards, the file structure looks like this:

.gitlab/analytics/dashboards
├── conversion_funnels
│  └── conversion_funnels.yaml
├── demographic_breakdown
│  └── demographic_breakdown.yaml
├── north_star_metrics
|  └── north_star_metrics.yaml
├── visualizations
│  └── example_line_chart.yaml

Dashboard filters

Dashboards support the following filters:

  • Date range: Date selector to filter data by date.
  • Anonymous users: Toggle to include or exclude anonymous users from the dataset.

To enable filters, in the .yaml configuration file set the filter's enabled option to true:

title: My dashboard
# ...
filters:
  excludeAnonymousUsers:
    enabled: true
  dateRange:
    enabled: true

See a complete dashboard configuration example.

Define an inline chart visualization

You can define different charts and add visualization options to some of them, such as:

  • Line chart, with the options listed in the ECharts documentation.
  • Column chart, with the options listed in the ECharts documentation.
  • Data table.
  • Single stat, with the only option to set decimalPlaces (number, default value is 0).

To add an inline chart visualization to a dashboard, see our Create a built-in dashboard guide. This process can also be followed for user-created dashboards. Each visualization must be written with the following required fields:

  • version
  • type
  • data
  • options

To contribute, see adding a new visualization render type.

Define a chart visualization template

We recommend using visualization templates sparingly. Visualization templates can lead to long visualization selection lists in the dashboard editor UI if not managed, which may lead to visualizations being missed or duplicated. Generally, visualization templates should be reserved for visualizations that will be used identically across several dashboards.

If you need a visualization to be used by multiple dashboards, you might store them as separate template files. When added to a dashboard, the visualization template will be copied over to the dashboard. Visualization templates copied to dashboards are not updated when the visualization template is updated.

To define a chart visualization template for your dashboards:

  1. In the .gitlab/analytics/dashboards/visualizations/ directory, create a .yaml file. The filename should be descriptive of the visualization it defines.
  2. In the .yaml file, define the visualization configuration, according to the schema in ee/app/validators/json_schemas/analytics_visualization.json.

For example, to create a line chart that illustrates event count over time, in the visualizations folder create a line_chart.yaml file with the following required fields:

  • version
  • type
  • data
  • options

Dashboard designer

Version history

  • Introduced in GitLab 16.1 with a flag named combined_analytics_dashboards_editor. Disabled by default.
  • Generally available in GitLab 16.6. Feature flag combined_analytics_dashboards_editor removed.
  • Changed to experiment in GitLab 17.11 with a flag named customizable_dashboards. Disabled by default.

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

You can use the dashboard designer to create and edit custom dashboards in the UI.

Create a custom dashboard

To create a custom dashboard:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Analyze > Analytics dashboards.
  3. Select New dashboard.
  4. In the New dashboard input, enter the name of the dashboard.
  5. From the Add visualizations list on the right, select the visualizations to add to the dashboard.
  6. Optional. Drag or resize the selected panel how you prefer.
  7. Select Save.

Edit a custom dashboard

You can edit your custom dashboard's title and add or resize and move panels in the dashboard designer.

To edit an existing custom dashboard:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Analyze > Analytics dashboards.
  3. From the list of available dashboards, select a custom dashboard (one without the By GitLab label) you want to edit.
  4. Select Edit.
  5. Optional. Change the title of the dashboard.
  6. Optional. From the Add visualizations list on the right, select other visualizations to add to the dashboard.
  7. Optional. In the dashboard, select a panel and drag or resize it how you prefer.
  8. Select Save.

Troubleshooting

Something went wrong while loading the dashboard.

If the dashboard displays a global error message that data could not be loaded, first try reloading the page. If the error persists:

  • Check that your configurations match the dashboard JSON schema defined in ee/app/validators/json_schemas/analytics_dashboard.json.

Invalid dashboard configuration

If the dashboard displays a global error message that the configuration is invalid, check that your configurations match the dashboard JSON schema defined in ee/app/validators/json_schemas/analytics_dashboard.json.

Invalid visualization configuration

If a dashboard panel displays a message that the visualization configuration is invalid, check that your visualization configurations match the visualization JSON schema defined in ee/app/validators/json_schemas/analytics_visualization.json.

Dashboard panel error

If a dashboard panel displays an error message:

  • Make sure your visualization configuration is set up correctly.