- Deprecation of bundled Grafana
- Configure Grafana
- Import dashboards
- Integrate with GitLab UI
- Required Scopes
- Security Update
Deprecated in GitLab 16.0.
Grafana is a tool that enables you to visualize time series metrics through graphs and dashboards. GitLab writes performance data to Prometheus, and Grafana allows you to query the data to display graphs.
Deprecation of bundled Grafana
Bundled Grafana was an optional Omnibus GitLab service that provided a user interface to GitLab metrics.
The version of Grafana that is bundled with Omnibus GitLab is no longer supported. If you’re using the bundled Grafana, you should switch to a newer version from Grafana Labs.
Switch to new Grafana instance
To switch away from bundled Grafana to a newer version of Grafana from Grafana Labs:
- Set up a version of Grafana from Grafana Labs.
- Export the existing dashboards from bundled Grafana.
- Import the existing dashboards in the new Grafana instance.
- Configure GitLab to use the new Grafana instance.
In GitLab versions 16.0 to 16.2, you can still force Omnibus GitLab to enable and configure Grafana by setting the following:
grafana['enable'] = true.
grafana['enable_deprecated_service'] = true.
You see a deprecation message when reconfiguring GitLab.
- Grafana installed.
- Log in to Grafana as the administration user.
- Select Data Sources from the Configuration menu.
- Select Add data source.
- Select the required data source type. For example, Prometheus.
- Complete the details for the data source and select Save & Test.
Grafana should indicate the data source is working.
You can now import a set of default dashboards to start displaying information. GitLab has published a set of default Grafana dashboards to get you started. To use them:
- Clone the repository, or download a ZIP file or tarball.
Follow these steps to import each JSON file individually:
- Log in to Grafana as the administration user.
- Select Manage from the Dashboards menu.
- Select Import, then Upload JSON file.
- Locate the JSON file to import and select Choose for Upload. Select Import.
- After the dashboard is imported, select the Save dashboard icon in the top bar.
If you don’t save the dashboard after importing it, the dashboard is removed when you navigate away from the page. Repeat this process for each dashboard you wish to import.
Alternatively, you can import all the dashboards into your Grafana instance. For more information about this process, see the README of the Grafana dashboards repository.
Integrate with GitLab UI
Introduced in GitLab 12.1.
After setting up Grafana, you can enable a link to access it from the GitLab sidebar:
- On the top bar, select Main menu > Admin.
- On the left sidebar, select Settings > Metrics and profiling and expand Metrics - Grafana.
- Select the Add a link to Grafana checkbox.
- Configure the Grafana URL:
If Grafana is enabled through Omnibus GitLab and on the same server,
leave Grafana URL unchanged. It should be
- Otherwise, enter the full URL of the Grafana instance.
- If Grafana is enabled through Omnibus GitLab and on the same server, leave Grafana URL unchanged. It should be
- Select Save changes.
GitLab displays your link in the Main menu > Admin > Monitoring > Metrics Dashboard.
Introduced in GitLab 13.10.
When setting up Grafana through the process above, no scope shows in the screen at
Main menu > Admin > Applications > GitLab Grafana. However, the
read_user scope is
required and is provided to the application automatically. Setting any scope other than
read_user without also including
read_user leads to this error when you try to sign in using
GitLab as the OAuth provider:
The requested scope is invalid, unknown, or malformed.
If you see this error, make sure that one of the following is true in the GitLab Grafana configuration screen:
- No scopes appear.
read_userscope is included.
Versions of GitLab prior 13.10 use the API scope instead of
read_user. In versions of GitLab prior to 13.10, the API scope:
- Is required to access Grafana through the GitLab OAuth provider.
- Is set by enabling the Grafana application as shown in Integration with GitLab UI.
Users running GitLab version 12.0 or later should immediately upgrade to one of the following security releases due to a known vulnerability with the embedded Grafana dashboard:
After upgrading, the Grafana dashboard is disabled, and the location of your
existing Grafana data is changed from
To prevent the data from being relocated, you can run the following command prior to upgrading:
echo "0" > /var/opt/gitlab/grafana/CVE_reset_status
To reinstate your old data, move it back into its original location:
sudo mv /var/opt/gitlab/grafana/data.bak.xxxx/ /var/opt/gitlab/grafana/data/
However, you should not reinstate your old data except under one of the following conditions:
- If you’re certain that you changed your default administration password when you enabled Grafana.
- If you run GitLab in a private network, accessed only by trusted users, and your Grafana login page has not been exposed to the internet.
If you require access to your old Grafana data but don’t meet one of these criteria, you may consider:
- Reinstating it temporarily.
- Exporting the dashboards you need.
- Refreshing the data and re-importing your dashboards.
For more information and further mitigation details, refer to our blog post on the security release.
Read more on: