Add support for GitHub App authentication

cspell.config.json

@@ -20,6 +20,7 @@
  "dfutil",
  "dserrors",
  "errorsource",
+ "ghinstallation",
  "githubclient",
  "githubv",
  "googlegithub",

docs/sources/setup/datasource.md

@@ -17,15 +17,15 @@ weight: 103
 
 # Configure the GitHub data source plugin for Grafana
 
-1. After creating the **personal access token** in GitHub, navigate into Grafana and click on the menu option on the top left.
+1. After creating the **access token** in GitHub, navigate into Grafana and click on the menu option on the top left.
 
 1. Browse to the **Connections** menu and then click on the **Data sources**.
 
 1. Click on the GitHub data source plugin which you have installed.
 
 1. Go to its settings tab and at the bottom, you will find the **Connection** section.
 
-1. Paste the personal access token.
+1. Paste the access token.
  ![Configuring API Token](/media/docs/grafana/data-sources/github/github-plugin-confg-token.png)
 
  (_Optional_): If you using the GitHub Enterprise, then select the **Enterprise** option inside the **Additional Settings** section and paste the URL of your GitHub Enterprise.

docs/sources/setup/token.md

@@ -1,7 +1,7 @@
 ---
-title: Create a GitHub personal access token
-menuTitle: Create a personal access token
-description: Create a GitHub personal access token
+title: Create a GitHub access token
+menuTitle: Create an access token
+description: Create a GitHub access token
 keywords:
  - data source
  - github
@@ -15,37 +15,38 @@ labels:
 weight: 102
 ---
 
-# Create a GitHub personal access token
+# Create a GitHub access token
 
-You will need a _personal access token_ to use the plugin. GitHub currently supports two types of personal access tokens:
-
-1. fine-grained personal access tokens
-1. personal access tokens (classic)
-
-Read more about [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
-
-The Grafana GitHub data source plugin works with both. Below is a table that indicates what minimum requirements must be matched before the plugin can be used.
-
-Options:
-
-| Setting | Required | Description |
-| --------------------- | -------- | ----------------------------------------------------- |
-| Access token | true | This is required to allow plugin to connect to GitHub |
-| GitHub Enterprise URL | false | Only if you are using GitHub Enterprise account |
+You will need either a `GitHub App` or a `Personal Access Token` to use this plugin.
 
 ## Creating a personal access token (classic)
 
-This is an example when you want to use the personal access token (classic).
+This is an example when you want to use the personal access token (classic). \
+Read more about [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
 
 1. Login to your GitHub account.
 1. Navigate to [Personal access tokens](https://github.com/settings/tokens) and click **Generate new token**.
 1. Select the **personal access token (classic)**.
 1. Define the permissions which you want to allow.
 1. Click **Generate Token**.
 
-### Permissions
+## Using GitHub App Authentication
+
+You can also authenticate using a GitHub App instead of a personal access token. This method allows for better security and fine-grained access to resources.
+
+1. Register a new GitHub App by following the instructions in the [GitHub App documentation](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
+1. After registering the App, generate a private key for authentication.
+1. Note down the App ID assigned to your GitHub App.
+1. [Install the GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app) on your GitHub account or organization.
+1. Note the installation ID after completing the installation.
+1. In Grafana's data source settings, provide the **app id**, **installation id**, and **private key** in the appropriate fields.
+
+> **Where to find your installation id?** \
+> Head over to Settings > Installed GitHub Apps > Configure. The installation ID can be found at the end of the URL `https://github.com/settings/installations/<installation_id>`.
+
+## Permissions
 
-You will need to define the access permissions for your token in order to allow it to access the data.
+You will need to define the access permissions for your **personal access token** in order to allow it to access the data.
 
 The following lists include the required permissions for the access token:
 

go.mod

@@ -1,10 +1,11 @@
 module github.com/grafana/github-datasource
 
-go 1.22
+go 1.23
 
-toolchain go1.22.1
+toolchain go1.23.1
 
 require (
+ github.com/bradleyfalzon/ghinstallation/v2 v2.11.0
  github.com/google/go-github/v53 v53.2.0
  github.com/grafana/grafana-plugin-sdk-go v0.250.0
  github.com/influxdata/tdigest v0.0.1
@@ -32,6 +33,8 @@ require (
  github.com/go-openapi/swag v0.22.8 // indirect
  github.com/goccy/go-json v0.10.2 // indirect
  github.com/gogo/protobuf v1.3.2 // indirect
+ github.com/golang-jwt/jwt/v4 v4.5.0 // indirect
+ github.com/google/go-github/v62 v62.0.0 // indirect
  github.com/google/go-querystring v1.1.0 // indirect
  github.com/google/uuid v1.6.0 // indirect
  github.com/gorilla/mux v1.8.1 // indirect

go.sum

@@ -9,6 +9,8 @@ github.com/araddon/dateparse v0.0.0-20210429162001-6b43995a97de h1:FxWPpzIjnTlhP
 github.com/araddon/dateparse v0.0.0-20210429162001-6b43995a97de/go.mod h1:DCaWoUhZrYW9p1lxo/cm8EmUOOzAPSEZNGF2DK1dJgw=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/bradleyfalzon/ghinstallation/v2 v2.11.0 h1:R9d0v+iobRHSaE4wKUnXFiZp53AL4ED5MzgEMwGTZag=
+github.com/bradleyfalzon/ghinstallation/v2 v2.11.0/go.mod h1:0LWKQwOHewXO/1acI6TtyE0Xc4ObDb2rFN7eHBAG71M=
 github.com/bufbuild/protocompile v0.4.0 h1:LbFKd2XowZvQ/kajzguUp2DC9UEIQhIq77fZZlaQsNA=
 github.com/bufbuild/protocompile v0.4.0/go.mod h1:3v93+mbWn/v3xzN+31nwkJfrEpAUwp+BagBSZWx+TP8=
 github.com/bwesterb/go-ristretto v1.2.0/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
@@ -60,6 +62,8 @@ github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang-jwt/jwt/v4 v4.5.0 h1:7cYmW1XlMY7h7ii7UhUyChSgS5wUJEnm9uZVTGqOWzg=
+github.com/golang-jwt/jwt/v4 v4.5.0/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/flatbuffers v23.5.26+incompatible h1:M9dgRyhJemaM4Sw8+66GHBu8ioaQmyPLg1b8VwK5WJg=
@@ -70,6 +74,8 @@ github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-github/v53 v53.2.0 h1:wvz3FyF53v4BK+AsnvCmeNhf8AkTaeh2SoYu/XUvTtI=
 github.com/google/go-github/v53 v53.2.0/go.mod h1:XhFRObz+m/l+UCm9b7KSIC3lT3NWSXGt7mOsAWEloao=
+github.com/google/go-github/v62 v62.0.0 h1:/6mGCaRywZz9MuHyw9gD1CwsbmBX8GWsbFkwMmHdhl4=
+github.com/google/go-github/v62 v62.0.0/go.mod h1:EMxeUqGJq2xRu9DYBMwel/mr7kZrzUOfQmmpYrZn2a4=
 github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
 github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=

pkg/github/client/client.go

@@ -9,6 +9,7 @@ import (
  "strconv"
  "time"
 
+ "github.com/bradleyfalzon/ghinstallation/v2"
  googlegithub "github.com/google/go-github/v53/github"
  "github.com/grafana/github-datasource/pkg/models"
  "github.com/grafana/grafana-plugin-sdk-go/backend"
@@ -52,11 +53,46 @@ var runnerPerMinuteRate = map[string]float64{
 
 // New instantiates a new GitHub API client.
 func New(ctx context.Context, settings models.Settings) (*Client, error) {
- if settings.AccessToken == "" {
- // If access token is not set, return downstream error as it is required.
- return nil, errorsource.DownstreamError(fmt.Errorf("access token is required"), false)
+ if settings.SelectedAuthType == "github-app" {
+ return createAppClient(settings)
  }
 
+ if settings.SelectedAuthType == "personal-access-token" {
+ return createAccessTokenClient(ctx, settings)
+ }
+
+ return nil, errorsource.DownstreamError(fmt.Errorf("access token or app token are required"), false)
+}
+
+func createAppClient(settings models.Settings) (*Client, error) {
+ appId, err := strconv.ParseInt(settings.AppId, 10, 64)
+ if err != nil {
+ return nil, errorsource.DownstreamError(fmt.Errorf("error parsing app id"), false)
+ }
+
+ installationId, err := strconv.ParseInt(settings.InstallationId, 10, 64)
+ if err != nil {
+ return nil, errorsource.DownstreamError(fmt.Errorf("error parsing installation id"), false)
+ }
+
+ itr, err := ghinstallation.New(http.DefaultTransport, appId, installationId, []byte(settings.PrivateKey))
+ if err != nil {
+ return nil, errorsource.DownstreamError(fmt.Errorf("error creating token source"), false)
+ }
+
+ httpClient := &http.Client{Transport: itr}
+
+ if settings.GitHubURL == "" {
+ return &Client{
+ restClient: googlegithub.NewClient(httpClient),
+ graphqlClient: githubv4.NewClient(httpClient),
+ }, nil
+ }
+
+ return useGitHubEnterprise(httpClient, settings)
+}
+
+func createAccessTokenClient(ctx context.Context, settings models.Settings) (*Client, error) {
  src := oauth2.StaticTokenSource(
  &oauth2.Token{AccessToken: settings.AccessToken},
  )
@@ -70,6 +106,10 @@ func New(ctx context.Context, settings models.Settings) (*Client, error) {
  }, nil
  }
 
+ return useGitHubEnterprise(httpClient, settings)
+}
+
+func useGitHubEnterprise(httpClient *http.Client, settings models.Settings) (*Client, error) {
  _, err := url.Parse(settings.GitHubURL)
  if err != nil {
  return nil, errorsource.DownstreamError(fmt.Errorf("incorrect enterprise url"), false)

pkg/github/datasource.go

@@ -2,7 +2,6 @@ package github
 
 import (
  "context"
- "fmt"
  "strings"
 
  "github.com/grafana/github-datasource/pkg/dfutil"
@@ -209,7 +208,7 @@ func (d *Datasource) QueryData(ctx context.Context, req *backend.QueryDataReques
 func NewDatasource(ctx context.Context, settings models.Settings) (*Datasource, error) {
  client, err := githubclient.New(ctx, settings)
  if err != nil {
- return nil, fmt.Errorf("instantiating github client: %w", err)
+ return nil, err
  }
  return &Datasource{client: client}, nil
 }

pkg/models/settings.go

@@ -6,14 +6,16 @@ import (
  "github.com/grafana/grafana-plugin-sdk-go/backend"
 )
 
-// Settings represents the Datasource options in Grafana
 type Settings struct {
- AccessToken string `json:"accessToken"`
- GitHubURL string `json:"githubUrl"`
- CachingEnabled bool `json:"cachingEnabled"`
+ SelectedAuthType string `json:"selectedAuthType"`
+ AccessToken string `json:"accessToken"`
+ PrivateKey string `json:"privateKey"`
+ AppId string `json:"appId"`
+ InstallationId string `json:"installationId"`
+ GitHubURL string `json:"githubUrl"`
+ CachingEnabled bool `json:"cachingEnabled"`
 }
 
-// LoadSettings converts the DataSourceInLoadSettings to usable GitHub settings
 func LoadSettings(settings backend.DataSourceInstanceSettings) (Settings, error) {
  s := Settings{}
  if err := json.Unmarshal(settings.JSONData, &s); err != nil {
@@ -24,5 +26,15 @@ func LoadSettings(settings backend.DataSourceInstanceSettings) (Settings, error)
  s.AccessToken = val
  }
 
+ if val, ok := settings.DecryptedSecureJSONData["privateKey"]; ok {
+ s.PrivateKey = val
+ }
+
+ // Data sources created before the auth type was introduced will have an accessToken but no auth type.
+ // In this case, we default to personal access token.
+ if s.AccessToken != "" && s.SelectedAuthType == "" {
+ s.SelectedAuthType = "personal-access-token"
+ }
+
  return s, nil
 }

pkg/plugin/instance.go

@@ -14,7 +14,7 @@ import (
 func NewGitHubInstance(ctx context.Context, settings models.Settings) (instancemgmt.Instance, error) {
  gh, err := github.NewDatasource(ctx, settings)
  if err != nil {
- return nil, fmt.Errorf("instantiating github datasource: %w", err)
+ return nil, err
  }
 
  var d Datasource = gh
@@ -37,7 +37,7 @@ func NewDataSourceInstance(_ context.Context, settings backend.DataSourceInstanc
 
  instance, err := NewGitHubInstance(context.Background(), datasourceSettings)
  if err != nil {
- return instance, fmt.Errorf("instantiating github instance")
+ return instance, fmt.Errorf("instantiating github instance: %w", err)
  }
 
  return instance, nil

src/types.ts

@@ -16,13 +16,34 @@
  githubUrl?: string;
 }
 
-export interface GitHubDataSourceOptions extends DataSourceJsonData, RepositoryOptions, GitHubEnterpriseOptions {
- // Any global settings
+export interface GitHubAppAuth {
+ appId?: string;
+ installationId?: string;
+}
+
+export interface GitHubDataSourceOptions
+ extends DataSourceJsonData,
+ RepositoryOptions,
+ GitHubEnterpriseOptions,
+ GitHubAppAuth {
+ selectedAuthType?: GitHubAuthType;
 }
 
 export interface GitHubSecureJsonData {
  // accessToken is set if the user is using a Personal Access Token to connect to GitHub
  accessToken?: string;
+ // privateKey is set if the user is using a GitHub App to connect to GitHub
+ privateKey?: string;
+}
+
+export enum GitHubAuthType {
+ Personal = 'personal-access-token',
+ App = 'github-app',
+}
+
+export enum GitHubLicenseType {
+ Basic = 'github-basic',
+ Enterprise = 'github-enterprise',
 }
 
 export enum QueryType {
@@ -133,7 +154,7 @@
  USER = 1,
 }
 
 export interface GitHubQuery extends Indexable, DataQuery, RepositoryOptions {
  options?:
  | PullRequestsOptions
  | ReleasesOptions

src/views/ConfigEditor.spec.tsx

@@ -9,6 +9,7 @@ describe('Config Editor', () => {
  const options = { jsonData: {}, secureJsonFields: {} } as any;
  render(<ConfigEditor options={options} onOptionsChange={onOptionsChange} />);
  await waitFor(() => expect(screen.getByText('Additional Settings')).toBeInTheDocument());
+ onOptionsChange.mockClear(); // this is called on component render, so we need to clear it to avoid false positives
  expect(screen.getByLabelText('Basic')).toBeChecked();
  expect(screen.getByLabelText('Enterprise')).not.toBeChecked();
  expect(screen.queryByText('GitHub Enterprise URL')).not.toBeInTheDocument();
@@ -22,6 +23,7 @@ describe('Config Editor', () => {
  const options = { jsonData: { githubUrl: 'https://foo.bar' }, secureJsonFields: {} } as any;
  render(<ConfigEditor options={options} onOptionsChange={onOptionsChange} />);
  await waitFor(() => expect(screen.getByText('Additional Settings')).toBeInTheDocument());
+ onOptionsChange.mockClear();
  expect(screen.getByLabelText('Basic')).not.toBeChecked();
  expect(screen.getByLabelText('Enterprise')).toBeChecked();
  expect(screen.queryByText('GitHub Enterprise URL')).toBeInTheDocument();