Plugins 〉GitHub
GitHub
Grafana GitHub datasource
The GitHub datasource allows GitHub API data to be visually represented in Grafana dashboards.
GitHub API V4 (GraphQL)
This datasource uses the githubv4
package, which is under active development.
Features
Backend
- <input checked="" disabled="" type="checkbox"> Releases
- <input checked="" disabled="" type="checkbox"> Commits
- <input checked="" disabled="" type="checkbox"> Repositories
- <input checked="" disabled="" type="checkbox"> Stargazers
- <input checked="" disabled="" type="checkbox"> Issues
- <input checked="" disabled="" type="checkbox"> Organizations
- <input checked="" disabled="" type="checkbox"> Labels
- <input checked="" disabled="" type="checkbox"> Milestones
- <input checked="" disabled="" type="checkbox"> Response Caching
- <input checked="" disabled="" type="checkbox"> Projects
- <input checked="" disabled="" type="checkbox"> Workflows
- <input disabled="" type="checkbox"> Deploys
Frontend
- <input checked="" disabled="" type="checkbox"> Visualize queries
- <input checked="" disabled="" type="checkbox"> Template variables
- <input checked="" disabled="" type="checkbox"> Annotations
Caching
Caching on this plugin is always enabled.
Configuration
Options:
Setting | Required |
---|---|
Access token | true |
Default Organization | false |
Default Repository | true |
GitHub Enterprise URL | false |
To create a new Access Token, navigate to Personal Access Tokens and press Generate new token.
Provisioning
It’s possible to configure data sources using config files with Grafana’s provisioning system.
With the prom-operator
promop:
grafana:
additionalDataSources:
- name: GitHub Repo Insights
type: grafana-github-datasource
jsonData:
owner: ''
repository: ''
secureJsonData:
accessToken: '<github api token>'
Annotations
Annotations overlay events on a graph.
With annotations, you can display:
- Commits
- Issues
- Pull Requests
- Releases
- Tags
on a graph.
All annotations require that you select a field to display on the annotation, and a field that represents the time that the event occurred.
Variables
Variables allow you to substitute values in a panel with pre-defined values.
You can reference them inside queries, allowing users to configure parameters such as Query
or Repository
.
Macros
You can use the following macros in your queries
Macro Name | Syntax | Description | Example |
---|---|---|---|
multiVar | $__multiVar(prefix,$var) | Expands a multi value variable into github query string | $__multiVar(label,$labels) will expand into label:first-label label:second-label |
When using all in multi variable, use * as custom all value | |||
day | $__toDay(diff) | Returns the day according to UTC time, a difference in days can be added | created:$__toDay(-7) on 2022-01-17 will expand into created:2022-01-10 |
Access Token Permissions
For all repositories:
public_repo
repo:status
repo_deployment
read:packages
read:user
user:email
For Github projects:
read:org
read:project
An extra setting is required for private repositories
repo (Full control of private repositories)
Sample Dashboard
For documentation on importing dashboards, check out the documentation on grafana.com
The sample dashboard can be obtained from either of two places.
From the Grafana dashboards page located here
From this repository
If loading it from this repository, open Grafana and click "Import Dashboard".
Copy the JSON in ./src/dashboards/dashboard.json
, and paste it into the "Import via panel json" box.
Frequently Asked Questions
- I am using GitHub OAuth on Grafana. Can my users make requests with their individual GitHub accounts instead of a shared
access_token
?
No. This requires changes in Grafana first. See this issue in the Grafana project.
- Why does it sometimes take up to 5 minutes for my new pull request / new issue / new commit to show up?
We have aggressive caching enabled due to GitHub's rate limiting policies. When selecting a time range like "Last hour", a combination of the queries for each panel and the time range is cached temporarily.
- Why are there two selection options for Pull Requests and Issue times when creating annotations?
There are two times that affect an annotation:
- The time range of the dashboard or panel
- The time that should be used to display the event on the graph
The first selection is used to filter the events that display on the graph. For example, if you select "closed at", only events that were "closed" in your dashboard's time range will be displayed on the graph.
The second selection is used to determine where on the graph the event should be displayed.
Typically these will be the same, however there are some cases where you may want them to be different.
Grafana Cloud Pro
- $25 / user / month and includes a free trial for new users
- Available with a Grafana Cloud Pro plan
- Access to 1 Enterprise plugin
- Fully managed service (not available to self-manage)
Grafana Cloud Advanced / Grafana Enterprise
- Available with a Grafana Cloud Advanced plan or Grafana Enterprise license
- Access to all Enterprise plugins
- Run fully managed or self-manage on your own infrastructure
Installing GitHub on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install GitHub from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Change Log
[1.5.3]
- Chore - Bump grafana-plugin-sdk-go to latest
- Chore - Added lint github workflow
- Chore - Remove legacy form styling
[1.5.2]
- BugFix - Fix config page backwards compatibility with Grafana < 10.1
[1.5.1] - 2023-10-10
- Feature - Update configuration page
- Chore - Update feature tracking usage to improve performance
[1.5.0] - 2023-09-13
- Feature - Issues Query: Allow repo to be optional
[1.4.7] - 2023-08-03
- Feature - Add ability to query Workflow and Workflow usage
[1.4.6] - 2023-07-14
- Bugfix - Fixed a bug where disabled queries were still being executed
[1.4.5] - 2023-05-04
- Chore - Backend binaries are now compiled with golang 1.20.4
[1.4.4] - 2023-04-19
- Chore - Updated go version to 1.20
[1.4.3] - 2023-03-07
- Chore - Update grafana-plugin-sdk-go to v0.155.0 to fix
The content of this plugin does not match its signature
error
[1.4.2] - 2023-03-06
- Chore - Migrate to create plugin and upgrade dependencies
[1.4.1] - 2023-03-01
- Feature - Added
RepositoryVulnerabilityAlertState
field toVulnerabilities
query
[1.4.0] - 2023-02-03
- Feature - Added stargazers query type
- Chore - Minor documentation updates
[1.3.3] - 2023-01-09
- Chore - Removed angular dependency: migrated annotation editor
[1.3.2] - next
- Feature Added
$__toDay()
macro support
[1.3.1] 2022-12-21
- Chore - Updated go version to latest (1.19.4)
- Chore - Updated backend grafana dependencies
- Chore - Added spellcheck
[1.3.0] 2022-11-3
- Feature - Github projects - query items, user projects
- Chore - Updated build to use go 1.19.3
[1.2.0] 2022-10-20
- Feature - Github projects
[1.1.0] - next
- Updated grafana minimum runtime required to 8.4.7
[1.0.15] 2022-05-05
- Fix variable interpolation
[1.0.14] 2022-04-25
- Added a
$__multiVar()
macro support
[1.0.13] 2021-12-01
- Fixed a bug where dashboard variables could not be set properly
[1.0.12] 2021-12-01
- Added refId in annotation queries
[1.0.11] 2021-05-17
- Added repository fields to the responses
[1.0.10] 2021-04-01
- Fixed issue where some time values were being rendered incorrectly
[1.0.9] 2021-04-01
- Fixed issue where dashboard path was not incorrect
[1.0.8] 2020-12-10
- Fixed issue where screenshots were not rendering on grafana.com (thanks @mjseaman)
[1.0.7] 2020-12-07
- Added Tags to the list of queryable resources in the AnnotationsQueryEditor ( thanks @nazzzzz)
[1.0.6] 2020-09-24
- Added a message to the healthcheck success status (thanks @vladimirdotk)
- Added URL option for GitHub Enterprise Users (thanks @bmike78)
[1.0.5] 2020-09-15
- Added Pull Request ID (Number), URL, and Repository name to pull request responses ( fixes #60 )
- Added the ability to search for all Pull Requests in an organization using the org: search term ( fixes #61 )
- Removed limit from repository list ( fixes #59 )
[1.0.3] 2020-09-11
- Add the ability to disable time field filtering for pull requests ( fixes #57 )
[1.0.1] 2020-09-11
- Add the ability to query repositories for variables ( fixes #52 )
- Fix scoped variables for repeating panels ( fixes #51 )
- The default time field for pull requests (Closed At) is now being displayed instead of an empty dropdown
[1.0.0] 2020-09-10
- Initial release