• Enabling Grafana
• Enable login using username and password
• Specifying an admin password
• Enable Grafana alerts
• Disabling Grafana
• Authentication
  • Using Grafana’s authentication system
  • Using GitLab as an OAuth provider
  • Resetting the admin password
• Dashboards
• Grafana metrics
  • Enabling Grafana’s metrics API
• Grafana SMTP
• Troubleshooting
  • X.509: certificate signed by unknown authority
  • The redirect URI included is not valid
  • Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method

Grafana Dashboard Service

Grafana is a powerful dashboard building system that you can use to visualize performance metrics from the embedded Prometheus monitoring system.

Enabling Grafana

Starting with GitLab 15.3, Grafana is not enabled by default. To enable it:

1. Edit /etc/gitlab/gitlab.rb and add/edit the following lines:

   ## Set to true/false to enable/disable respectively
   grafana['enable'] = true
   

2. Save the file and reconfigure GitLab for the changes to take effect.
3. Once enabled, Grafana will be available on https://gitlab.example.com/-/grafana and SSO with GitLab is automatically configured.

Enable login using username and password

Logging in to Grafana using username/password combo is disabled, and only GitLab SSO is available by default. However, to access the admin account, you need to enable login using username/password. For that, add the following line to /etc/gitlab/gitlab.rb file and reconfigure:

grafana['disable_login_form'] = false

Specifying an admin password

To specify an admin password, add the following line to /etc/gitlab/gitlab.rb file and reconfigure:

grafana['admin_password'] = 'foobar'

If no admin password is provided, Omnibus GitLab will automatically generate a random password for the admin user as a security measure. However, in that case you will have to reset the password manually to access the admin user.

Enable Grafana alerts

Grafana can provide the ability to create alerts based on rules that you configure in your dashboard. By default, alerts are disabled in the bundled Grafana instance.

To enable Grafana alerts:

1. Edit /etc/gitlab/gitlab.rb and add the following line:

   grafana['alerting_enabled'] = true
   

2. Save the file and reconfigure GitLab:

   sudo gitlab-ctl reconfigure
   

Disabling Grafana

1. Edit /etc/gitlab/gitlab.rb and add/edit the following lines:

   ## Set to true/false to enable/disable respectively
   grafana['enable'] = false
   

2. Save the file and reconfigure GitLab for the changes to take effect.

Authentication

If you want to give a user access to Grafana, you have two options.

Using Grafana’s authentication system

To allow users to create their own accounts in Grafana:

1. Edit /etc/gitlab/gitlab.rb and add the following lines:

   grafana['allow_user_sign_up'] = true
   

2. Save the file and reconfigure GitLab for the changes to take effect.

Using GitLab as an OAuth provider

To use GitLab as an OAuth provider so that users of your GitLab instance have access to Grafana:

1. First, create an application ID and secret.

2. Set the callback URL based on your external_url. For example https://gitlab.example.com/-/grafana/login/gitlab.

3. Then, edit /etc/gitlab/gitlab.rb and add the following lines:

   grafana['gitlab_application_id'] = 'GITLAB_APPLICATION_ID'
   grafana['gitlab_secret'] = 'GITLAB_SECRET'
   

   Where GITLAB_APPLICATION_ID and GITLAB_SECRET the application ID and its secret that you created in the previous step.

4. Optionally, you can select a list of GitLab groups allowed to log in:

   grafana['allowed_groups'] = [my_group, group_one/group_two]
   

5. Save the file and reconfigure GitLab for the changes to take effect.

Resetting the admin password

After the first startup, the admin password is stored in the Grafana datastore and you cannot change it via gitlab.rb.

To update it, you can use the following command:

gitlab-ctl set-grafana-password

See the Grafana CLI documentation for more information.

Dashboards

Starting with GitLab 11.10, dashboards for monitoring Omnibus GitLab will be pre-loaded and available on initial login.

For earlier versions of GitLab, you can manually import the pre-built dashboards that are tailored for Omnibus installations.

Grafana metrics

Grafana can provide metrics to be scraped by Prometheus.

By default, the metrics API is disabled in the bundled Grafana instance.

Enabling Grafana’s metrics API

To enable Grafana’s metrics API with basic authentication:

1. Edit /etc/gitlab/gitlab.rb and add/edit the following lines:

   grafana['metrics_enabled'] = true
   grafana['metrics_basic_auth_username'] = 'grafana_metrics'
   grafana['metrics_basic_auth_password'] = 'please_set_a_unique_password'
   

2. Save the file and reconfigure GitLab for the changes to take effect.

3. The metrics will be available at https://gitlab.example.com/-/grafana/metrics with basic authentication. The username and password for basic authentication will be the metrics_basic_auth_username and metrics_basic_auth_password that was set in /etc/gitlab/gitlab.rb.

Grafana SMTP

Enable SMTP to allow Grafana to send emails:

grafana['smtp']['enabled'] = true

To fully customize Grafana’s SMTP configuration, use the following code snippet as a starting point:

grafana['smtp'] = {
  'enabled' => true,
  'host' => 'localhost:25',
  'user' => nil,
  'password' => nil,
  'cert_file' => nil,
  'key_file' => nil,
  'skip_verify' => false,
  'from_address' => 'admin@grafana.localhost',
  'from_name' => 'Grafana',
  'ehlo_identity' => 'dashboard.example.com',
  'startTLS_policy' => nil
}

For more information on Grafana’s SMTP configuration see Grafana’s documentation.

Troubleshooting

X.509: certificate signed by unknown authority

When using a self-signed SSL certificate for GitLab, you may get the following error in the UI:

login.OAuthLogin(NewTransportWithCode)

Check the Grafana server logs for the detailed error message.

The error reported in the Grafana logs at /var/log/gitlab/grafana/current can be:

lvl=eror msg=login.OAuthLogin(NewTransportWithCode) logger=context userId=0 orgId=0 uname= error="Post \"https://gitlab.example.com/oauth/token\": x509: certificate signed by unknown authority"

In this case, you must install the self-signed GitLab certificate as trusted.

The redirect URI included is not valid

An incorrect callback URL commonly causes this error. You may get this error when trying to log in to Grafana if the Callback URL is not correct. To fix that:

1. On the top bar, select Main menu > Admin.
2. On the left sidebar, select Applications.
3. Select Edit of the GitLab Grafana application.
4. Change the value of Callback URL to look like https://gitlab.example.com/-/grafana/login/gitlab where https://gitlab.example.com corresponds to your external_url.

Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method

These errors may happen if the GitLab Grafana OAuth application does not exist or the settings in /etc/gitlab/gitlab-secrets.json are no longer consistent with each other.

To fix it:

1. On the top bar, select Main menu > Admin.
2. On the left sidebar, select Applications.
3. Remove the application GitLab Grafana if it exists by selecting Destroy.
4. Create a backup of /etc/gitlab/gitlab-secrets.json on your GitLab server.

5. Edit /etc/gitlab/gitlab-secrets.json and remove the section starting with grafana. You can find the relevant section with:

   $ grep grafana -A6 /etc/gitlab/gitlab-secrets.json
   
   "grafana": {
   "secret_key": "...",
   "gitlab_secret": "...",
   "gitlab_application_id": "...",
   "admin_password": "...",
   "metrics_basic_auth_password": null
   },
   

6. Reconfigure GitLab to re-create the GitLab Grafana application and regenerate the values in /etc/gitlab/gitlab-secrets.json:

   sudo gitlab-ctl reconfigure