Documentation Plugins GitHub data source Template variables

GitHub template variables

Use template variables to create dynamic, reusable dashboards with the GitHub data source. For general information about variables in Grafana, refer to Variables.

Before you begin

• Configure the GitHub data source.
• Familiarize yourself with the available query types.

Supported variable types

The GitHub data source supports Query variables. You can use any query type (for example, Repositories, Labels, Issues) to populate variable options.

Create a query variable

To create a query variable:

1. Navigate to Dashboard settings > Variables.
2. Click Add variable.
3. Select Query as the variable type.
4. Select the GitHub data source from the Data source drop-down.
5. Select the Query Type (for example, Repositories, Labels, or any other supported query type).
6. Configure the query options for the selected query type.
7. Set Field Value to the response field that provides the variable values (the actual value stored when a user selects an option).
8. Set Field Display to the response field that provides the display labels (the text shown in the drop-down).

Use variables in queries

You can reference variables in any string field in the query editor, such as Owner, Repository, or Query, using the standard Grafana variable syntax:

• $variable or ${variable} for single-value variables.
• Variables with multiple selected values are interpolated as comma-separated values.

For example, to create a dashboard that lets users select a repository:

1. Create a variable named repo using the Repositories query type.
2. In your query, set Repository to $repo.

Macros

The GitHub data source provides macros that add dynamic parts to your queries. Macros are used in the Query field, which is available on query types that support GitHub search syntax, such as Issues, Pull Requests, and Pull Request Reviews.

Use multiVar with “All” selection

When using the $__multiVar macro with a multi-value variable, set the Custom all value to * in the variable settings. When “All” is selected, the macro returns an empty string, which removes that qualifier from the query.

Macro examples

Filter issues by multiple labels selected from a variable:

• Query: is:open $__multiVar(label,$labels)

Filter issues created in the last 7 days:

• Query: is:open created:>=$__toDay(-7)

Combine macros for a dynamic query:

• Query: is:open $__multiVar(label,$labels) created:>=$__toDay(-30)

Use case: Multi-variable dashboard

You can chain variables together to build a dashboard that lets users drill down from an organization to a specific repository and filter by labels.

Set up the variables

Create the following variables in order. Later variables reference earlier ones, so the order matters.

1. owner — Type: Custom. Add a comma-separated list of your GitHub organizations or user accounts (for example, grafana,prometheus). This provides the top-level organization selector.

2. repo — Type: Query. Use the Repositories query type with Owner set to $owner. Set Field Value and Field Display to name. This populates the repository drop-down based on the selected organization.

3. labels — Type: Query, Multi-value enabled. Use the Labels query type with Owner set to $owner and Repository set to $repo. Set Field Value and Field Display to name. Set Custom all value to *. This lets users filter by one or more labels.

Use the variables in panels

With these variables in place, build panels that respond to all three selectors:

• Open issues panel: Set Owner to $owner, Repository to $repo, and Query to is:open $__multiVar(label,$labels).
• Pull request panel: Set Owner to $owner, Repository to $repo, and Query to is:open $__multiVar(label,$labels).
• Commits panel: Set Owner to $owner and Repository to $repo to show commit activity for the selected repository.

When a user changes the organization drop-down, the repository list refreshes automatically. Selecting a different repository updates the label list and all panels on the dashboard.