Documentation Plugins GitHub data source Configure

Configure the GitHub data source

This document explains how to configure the GitHub data source for Grafana.

Before you begin

To configure the data source, you need:

• Grafana permissions: Organization administrator role.
• GitHub credentials (one of the following):
  • A personal access token (classic or fine-grained) with the required scopes.
  • A registered GitHub App with the App ID, Installation ID, and private key. Refer to Register and configure a GitHub App for setup steps.
• GitHub Enterprise Server URL (if applicable): The URL of your GitHub Enterprise Server instance.

Security best practices

When creating credentials for the GitHub data source, follow the principle of least privilege:

• Prefer GitHub Apps or fine-grained tokens over classic PATs. GitHub Apps and fine-grained tokens let you restrict access to specific repositories and grant only the permissions the plugin needs. Classic personal access tokens grant access to all repositories the user can access.
• Grant only read-only permissions. The data source only reads data from GitHub. Never grant write access unless you have a specific requirement.
• Scope tokens to the repositories you need. Avoid granting organization-wide access when you only query a few repositories.
• Rotate credentials regularly. Set an expiration on personal access tokens and rotate them on a regular schedule. GitHub Apps use short-lived tokens that rotate automatically.

Grafana stores all credentials (access tokens, private keys) as encrypted secure JSON data. Credentials are never exposed in API responses or log output.

Add the data source

To add the GitHub data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type GitHub in the search bar.
4. Select GitHub.
5. Click Add new data source.

Configure settings

The following table describes the GitHub-specific configuration settings.

Private data source connect

Private data source connect (PDC) establishes a private, secured connection between a Grafana Cloud stack and data sources within a private network. Use the drop-down to select a PDC connection.

Click Manage private data source connect to go to your PDC connection page, where you can find your PDC configuration details.

For setup instructions, refer to Private data source connect.

Authentication

The GitHub data source supports two authentication methods: personal access tokens and GitHub Apps.

Personal access token

You can authenticate with either a classic personal access token or a fine-grained personal access token.

Create a classic personal access token

1. Sign in to your GitHub account.
2. Navigate to Personal access tokens and click Generate new token.
3. Select personal access token (classic).
4. Assign the required permissions.
5. Click Generate Token.
6. Copy the token and paste it into the Personal Access Token field in the data source settings.

For more information, refer to the GitHub personal access token documentation.

Create a fine-grained personal access token

1. Sign in to your GitHub account.
2. Navigate to Fine-grained personal access tokens and click Generate new token.
3. Provide a name for the token.
4. Assign the required repository access and read-only permissions.
5. Click Generate token.
6. Copy the token and paste it into the Personal Access Token field in the data source settings.

For more information, refer to the GitHub fine-grained personal access token documentation.

Personal access token permissions

The following scopes are required for classic personal access tokens:

GitHub App

GitHub App authentication provides better security and fine-grained access to resources compared to personal access tokens.

Register and configure a GitHub App

1. Register a new GitHub App by following the GitHub App documentation.
2. After registering the app, generate a private key for authentication.
3. Note the App ID assigned to your GitHub App.
4. Install the GitHub App on your GitHub account or organization.
5. Note the Installation ID after completing the installation.
6. In the Grafana data source settings, provide the App ID, Installation ID, and Private Key in the appropriate fields.

GitHub App permissions

The following repository permissions are required:

Code scanning permissions

To use the code scanning query type, the following additional permissions are required for both personal access tokens and GitHub Apps:

For classic personal access tokens, add the security_events scope.

Verify the connection

After you have added your GitHub connection settings, click Save & test to test and save the data source connection. When the connection is successful, you see the message Data source is working.

If the connection fails, check the following error messages:

Provision the data source

You can define the data source in YAML files as part of Grafana’s provisioning system. For more information, refer to Provision Grafana.

Personal access token example

YAML Copy

apiVersion: 1

datasources:
  - name: GitHub
    type: grafana-github-datasource
    jsonData:
      selectedAuthType: personal-access-token
    secureJsonData:
      accessToken: <ACCESS_TOKEN>

GitHub App example

YAML Copy

apiVersion: 1

datasources:
  - name: GitHub
    type: grafana-github-datasource
    jsonData:
      selectedAuthType: github-app
      appId: <APP_ID>
      installationId: <INSTALLATION_ID>
    secureJsonData:
      privateKey: <PRIVATE_KEY>

GitHub Enterprise Server example

YAML Copy

apiVersion: 1

datasources:
  - name: GitHub Enterprise
    type: grafana-github-datasource
    jsonData:
      selectedAuthType: personal-access-token
      githubPlan: github-enterprise-server
      githubUrl: https://github.example.com
    secureJsonData:
      accessToken: <ACCESS_TOKEN>

Provision with Terraform

You can provision the GitHub data source using the Grafana Terraform provider. For more information, refer to Provision Grafana with Terraform.

Personal access token example

hcl Copy

resource "grafana_data_source" "github" {
  type = "grafana-github-datasource"
  name = "GitHub"

  json_data_encoded = jsonencode({
    selectedAuthType = "personal-access-token"
  })

  secure_json_data_encoded = jsonencode({
    accessToken = var.github_access_token
  })
}

GitHub App example

hcl Copy

resource "grafana_data_source" "github" {
  type = "grafana-github-datasource"
  name = "GitHub"

  json_data_encoded = jsonencode({
    selectedAuthType = "github-app"
    appId            = var.github_app_id
    installationId   = var.github_installation_id
  })

  secure_json_data_encoded = jsonencode({
    privateKey = var.github_private_key
  })
}