Menu
Documentationbreadcrumb arrow Pluginsbreadcrumb arrow GitLab data source for Grafana

GitLab data source for Grafana

The GitLab data source plugin allows you to keep track of detailed GitLab statistics, such as top contributors, commits per day, or deployments per day. You can also use template variables, such as projects, to set up filters for your dashboards. You can combine data from the GitLab API with data from other sources.

Requirements

This plugin has the following requirements:

Install the GitLab data source plugin

To install the data source, refer to Installation

Configure GitLab

Create a personal access token with permissions for the read_api scope:

  1. Go to your Personal Access Tokens.
  2. Fill in the Name and Expires at fields.
  3. From Scopes, select read_api.
  4. Click the Create personal access token button, and copy your personal access token.

Configure the data source in Grafana

Add a data source by filling in the following fields:

Name
A name for this particular GitLab data source
URL
The root URL for your GitLab instance, e.g. https://gitlab.com/api/v4.
Access token
our GitLab personal access token.

Configure the data source with provisioning

It is possible to configure data sources using config files with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page

YAML 
apiVersion: 1

datasources:
  - name: GitLab
    type: grafana-gitlab-datasource
    access: proxy
    basicAuth: false
    editable: true
    enabled: true
    secureJsonData:
      accessToken: Access token
    url: https://gitlab.com
    version: 1

Query the data source

You can select different resource types from the query editor.

Resource types:

  • Audit Events
  • Commits
  • Deployments
  • Environments
  • Issues
  • Labels
  • Merge Request Approvals
  • Merge Requests
  • Pipelines
  • Projects
  • Releases
  • Tags
  • Users

Audit events

The GitLab data source allows you to query for audit events related to the set Gitlab account, a specified project or a specified group. This feature is limited to Premium accounts (for project/group queries) or hosted gitlab with admin privileges (for instance queries).

  1. Select the resource type:

    Use the dropdown and select the Audit Events resource type.

  2. Fill the options as needed:

    On cloud instance audit events can be queried by project or group only. If no project ID or group ID is set, then the datasource will return an error. On self-hosted gitlab neither of those options are required and datasource will then return all audit events related to the account.

Commits

The GitLab data source allows you to query for commits authored on a specific project.

  1. Select the resource type:

    Use the dropdown and select the Commits resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

  3. (Optional) Filter by branch/tag.

    Use the input field to add a branch/tag reference.

Deployments

The GitLab data source allows you to query for deployments from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Deployments resource type.

  2. Add the project Id:

    Use the input field to add the project Id:

  3. (Optional) Filter by environment/status

    Use the input fields to filter by environment and/or status.

    The status attribute can be one of the following values: created,running,success,failed, and canceled.

Environments

The GitLab data source allows you to query for environments from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Environments resource type.

  2. Fill the options as needed:

    Use the input field to add the project Id and filter through environments by setting the rest of the fields.

Issues

The GitLab data source allows you to query for issues from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Issues resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

  3. (Optional) Filter by title/description:

    Use the input field to search issues against their title and description.

Labels

The GitLab data source allows you to query for labels from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Labels resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

Merge request approvals

The GitLab data source allows you to get a specific merge request approval.

  1. Select the resource type:

    Use the dropdown and select the Merge Request approval resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

  3. Add the merge request Id

    Use the input field to add the merge request Id.

Merge requests

The GitLab data source allows you to query for merge requests related to the set Gitlab account, a specified project or a specified group.

  1. Select the resource type:

    Use the dropdown and select the Merge requests resource type.

  2. Fill the options as needed:

    Merge requests can be queried by various fields. If no project Id or group Id is set, then the data source will return all merge requests related to the specified GitLab account.

Pipelines

The GitLab data source allows you to query for pipelines from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Pipelines resource type.

  2. Fill the options as needed:

    Use the input field to add the project Id and filter through pipelines by setting the rest of the fields.

Projects

The GitLab data source allows you to query for projects.

  1. From the dropdown menu select the Projects resource type.
  2. (Optional) Filter by the projects that you own

Use the dropdown and select Yes or No to filter the results.

NOTE: Consider that fetching all the projects (Owned = No) may take long time.

Releases

The GitLab data source allows you to query for releases from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Releases resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

Tags

The GitLab data source allows you to query for tags from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Tags resource type.

  2. Add the project Id:

    Use the input field to add the project Id.

  3. (Optional) Filter by search:

    Use the input field to search tags against their name. You can use ^term and term$ to find tags that begin and end with term.

Users

The GitLab data source allows you to query for users. You must be an admin to use most fields.

  1. Select the resource type:

    Use the dropdown and select the Users resource type.

  2. Fill the options as needed:

    Users can be queried by various fields. If a username is not provided,it will return users you are an admin of and filtered by the other fields.

Templates and variables

To add a new GitLab query variable, refer to Add a query variable. Use your GitLab data source as your data source. Choose a resource type: Releases, Projects, or Labels.

To get a dynamic list of Projects, Labels, etc to choose from, create a Query type variable.
Query type variables use the GitLab Query Editor to query and return Projects, Labels, etc.

Example: Create a Project variable to parameterize your queries.

  1. Add a variable of type Query named project
  2. Select your GitLab data source and refresh On Dashboard Load.
  3. Select resource type: Projects, owned: Yes, display field: name and value field id.
  4. Click Update to add the variable to the dashboard.
  5. A dropdown appears on your dashboard with a list of projects.
  6. Add a new panel to the dashboard and use $project as the project Id.
  7. Now when choosing from the dropdown, you get the results that belong to that project.

After creating a variable, you can use it in your GitLab queries by using Variable syntax. For more information about variables, refer to Templates and variables.

Using Transformations from Grafana to answer common questions

Now that you can perform basic GitLab queries to find commits, issues, etc, you can use Transformations to visualize, aggregate, group, and join datasets, along with many other types of transformations to transform simple results into answers for complex questions. Below are a few common questions and how to use transformations to answer them.

Question: How many commits / issues / deployments per day in my project?

  1. Add a query:

    a. Select resource type: Commits.

    b. Add the project Id.

  2. Add a new Group by transformation:

    a. Group by = created_at_date.

    b. Calculate (Count) = id.

  3. Select the Graph visualization.

Question: What is the average time to close issues in my project?

  1. Add a query:

    a. Select resource type: Issues.

    b. Add the project Id.

  2. Add a new Add field from calculation transformation:

    a. Mode = Binary Operation.

    b. Operation = closed_at - created_at.

    c. Alias = resolution_time.

  3. Add a new Add field from calculation transformation:

    a. Mode = Binary Operation.

    b. Operation = resolution_time / 86400000 (1000 * 3600 * 24) …to get days.

    c. Alias = resolution_time.

    d. Replace all fields = True.

  4. Select the Stat visualization:

    a. Show = Calculate.

    b. Calculation = Mean.

    c. Fields = resolution_time.

Get the most out of the plugin