feat(scorecard): fetch github open PRs (#1372)

* Introduce fetching github PRs

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>
Assisted-by: Cursor Desktop

* Use directly octokit graphql

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>

* Introduce tests

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>
Assisted-by: Cursor Desktop

* Add docs

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>
Assisted-by: Cursor Desktop

* Update auth to octokit/graphql

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>

* Introduce github constants

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>

* Support octokit esm

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>

---------

Signed-off-by: Dominika Zemanovicova <dzemanov@redhat.com>

Author: dzemanov

workspaces/scorecard/app-config.yaml

@@ -94,6 +94,9 @@ catalog:
       rules:
         - allow: [User, Group]
 
+    - type: url
+      target: https://github.com/redhat-developer/rhdh/blob/main/catalog-entities/components/showcase.yaml
+
     ## Uncomment these lines to add more example data
     # - type: url
     #   target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all.yaml

workspaces/scorecard/package.json

@@ -17,8 +17,8 @@
     "build-image": "yarn workspace backend build-image",
     "build:knip-reports": "backstage-repo-tools knip-reports",
     "clean": "backstage-cli repo clean",
-    "test": "backstage-cli repo test",
-    "test:all": "backstage-cli repo test --coverage",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' backstage-cli repo test",
+    "test:all": "NODE_OPTIONS='--experimental-vm-modules' backstage-cli repo test --coverage",
     "test:e2e": "playwright test",
     "fix": "backstage-cli repo fix",
     "lint": "backstage-cli repo lint --since origin/main",

workspaces/scorecard/plugins/scorecard-backend-module-github/README.md

@@ -1,5 +1,92 @@
-# @@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-github
+# Scorecard Backend Module for GitHub
 
-The github backend module for the scorecard plugin.
+This is an extension module to the `backstage-plugin-scorecard-backend` plugin. It provides GitHub-specific metrics for software components registered in the Backstage catalog.
 
-_This plugin was created through the Backstage CLI_
+## Prerequisites
+
+Before installing this module, ensure that the Scorecard backend plugin is integrated into your Backstage instance. Follow the [Scorecard backend plugin README](../scorecard-backend/README.md) for setup instructions.
+
+This module also requires a GitHub integration to be configured in your `app-config.yaml`. It uses Backstage's standard GitHub integration configuration, you can check the [docs](https://backstage.io/docs/integrations/github/locations/#configuration) to see all options.
+
+## Installation
+
+To install this backend module:
+
+```bash
+# From your root directory
+yarn workspace backend add @red-hat-developer-hub/backstage-plugin-scorecard-backend-module-github
+```
+
+```ts
+// packages/backend/src/index.ts
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+
+// Scorecard backend plugin
+backend.add(
+  import('@red-hat-developer-hub/backstage-plugin-scorecard-backend'),
+);
+
+// Install the GitHub module
+/* highlight-add-next-line */
+backend.add(
+  import(
+    '@red-hat-developer-hub/backstage-plugin-scorecard-backend-module-github'
+  ),
+);
+
+backend.start();
+```
+
+### Entity Annotations
+
+For the GitHub metrics to work, your catalog entities must have the required GitHub annotations:
+
+```yaml
+# catalog-info.yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-service
+  annotations:
+    # Required: GitHub project slug in format "owner/repository"
+    github.com/project-slug: myorg/my-service
+spec:
+  type: service
+  lifecycle: production
+  owner: team-a
+```
+
+## Available Metrics
+
+### GitHub Open Pull Requests (`github.open-prs`)
+
+This metric counts all pull requests that are currently in an "open" state for the repository specified in the entity's `github.com/project-slug` annotation.
+
+- **Metric ID**: `github.open-prs`
+- **Type**: Number
+- **Datasource**: `github`
+- **Default thresholds**:
+
+  ```yaml
+  # app-config.yaml
+  scorecard:
+    plugins:
+      github:
+        open_prs:
+          thresholds:
+            rules:
+              - key: error
+                expression: '>50'
+              - key: warning
+                expression: '10-50'
+              - key: success
+                expression: '<10'
+  ```
+
+## Configuration
+
+### Threshold Configuration
+
+Thresholds define conditions that determine which category a metric value belongs to ( `error`, `warning`, or `success`). You can configure custom thresholds for the GitHub metrics. Check out detailed explanation of [threshold configuration](../scorecard-backend/docs/thresholds.md).

workspaces/scorecard/plugins/scorecard-backend-module-github/package.json

@@ -33,19 +33,21 @@
     "prepack": "backstage-cli package prepack",
     "postpack": "backstage-cli package postpack",
     "start": "backstage-cli package start",
-    "test": "backstage-cli package test",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' backstage-cli package test",
     "tsc": "tsc",
     "prettier:check": "prettier --ignore-unknown --check .",
     "prettier:fix": "prettier --ignore-unknown --write ."
   },
   "dependencies": {
     "@backstage/backend-plugin-api": "^1.4.1",
+    "@backstage/catalog-model": "^1.7.5",
+    "@backstage/integration": "^1.16.0",
+    "@octokit/graphql": "^9.0.1",
     "@red-hat-developer-hub/backstage-plugin-scorecard-common": "workspace:^",
     "@red-hat-developer-hub/backstage-plugin-scorecard-node": "workspace:^"
   },
   "devDependencies": {
     "@backstage/backend-test-utils": "^1.7.0",
-    "@backstage/catalog-model": "^1.7.5",
     "@backstage/cli": "^0.33.1",
     "@backstage/config": "^1.3.3"
   },

workspaces/scorecard/plugins/scorecard-backend-module-github/src/github/GitHubClient.test.ts

@@ -0,0 +1,92 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ConfigReader } from '@backstage/config';
+import { DefaultGithubCredentialsProvider } from '@backstage/integration';
+import { GithubClient } from './GithubClient';
+import { GithubRepository } from './types';
+import { DEFAULT_GITHUB_HOSTNAME } from './constants';
+
+describe('GithubClient', () => {
+  let githubClient: GithubClient;
+  const mockedGraphqlClient = jest.fn();
+  const repository: GithubRepository = {
+    owner: 'owner',
+    repo: 'repo',
+  };
+
+  jest
+    .spyOn(DefaultGithubCredentialsProvider.prototype, 'getCredentials')
+    .mockResolvedValue({
+      type: 'token',
+      headers: { Authorization: 'Bearer dummy-token' },
+      token: 'dummy-token',
+    });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // @ts-ignore
+    jest.unstable_mockModule('@octokit/graphql', async () => ({
+      graphql: {
+        defaults: () => mockedGraphqlClient,
+      },
+    }));
+
+    const mockConfig = new ConfigReader({
+      integrations: {
+        github: [
+          {
+            host: DEFAULT_GITHUB_HOSTNAME,
+            token: 'dummy-token',
+          },
+        ],
+      },
+    });
+    githubClient = new GithubClient(mockConfig);
+  });
+
+  describe('getOpenPullRequestsCount', () => {
+    it('should return the count of open pull requests', async () => {
+      const response = {
+        repository: {
+          pullRequests: {
+            totalCount: 42,
+          },
+        },
+      };
+      mockedGraphqlClient.mockResolvedValue(response);
+
+      const result = await githubClient.getOpenPullRequestsCount(
+        repository,
+        DEFAULT_GITHUB_HOSTNAME,
+      );
+
+      expect(result).toBe(42);
+      expect(mockedGraphqlClient).toHaveBeenCalledTimes(1);
+      expect(mockedGraphqlClient).toHaveBeenCalledWith(
+        expect.stringContaining('query getOpenPRsCount'),
+        repository,
+      );
+    });
+
+    it('should throw error when GitHub integration for hostname is missing', async () => {
+      await expect(
+        githubClient.getOpenPullRequestsCount(repository, 'unknown-host'),
+      ).rejects.toThrow("Missing GitHub integration for 'unknown-host'");
+    });
+  });
+});

workspaces/scorecard/plugins/scorecard-backend-module-github/src/github/GithubClient.ts

@@ -0,0 +1,83 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Config } from '@backstage/config';
+import {
+  DefaultGithubCredentialsProvider,
+  ScmIntegrations,
+} from '@backstage/integration';
+import { GithubRepository } from './types';
+import { DEFAULT_GITHUB_HOSTNAME } from './constants';
+
+export class GithubClient {
+  private readonly integrations: ScmIntegrations;
+
+  constructor(config: Config) {
+    this.integrations = ScmIntegrations.fromConfig(config);
+  }
+
+  private async getOctokitClient(
+    hostname: string = DEFAULT_GITHUB_HOSTNAME,
+  ): Promise<typeof graphql> {
+    const githubIntegration = this.integrations.github.byHost(hostname);
+    if (!githubIntegration) {
+      throw new Error(`Missing GitHub integration for '${hostname}'`);
+    }
+
+    const credentialsProvider =
+      DefaultGithubCredentialsProvider.fromIntegrations(this.integrations);
+
+    const { headers } = await credentialsProvider.getCredentials({
+      url: `https://${hostname}`,
+    });
+
+    const { graphql } = await import('@octokit/graphql');
+    return graphql.defaults({
+      headers,
+      baseUrl: githubIntegration.config.apiBaseUrl,
+    });
+  }
+
+  async getOpenPullRequestsCount(
+    repository: GithubRepository,
+    hostname: string,
+  ): Promise<number> {
+    const octokit = await this.getOctokitClient(hostname);
+
+    const query = `
+      query getOpenPRsCount($owner: String!, $repo: String!) {
+        repository(owner: $owner, name: $repo) {
+          pullRequests(states: OPEN) {
+            totalCount
+          }
+        }
+      }
+    `;
+
+    const response = await octokit<{
+      repository: {
+        pullRequests: {
+          totalCount: number;
+        };
+      };
+    }>(query, {
+      owner: repository.owner,
+      repo: repository.repo,
+    });
+
+    return response.repository.pullRequests.totalCount;
+  }
+}

workspaces/scorecard/plugins/scorecard-backend-module-github/src/github/constants.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const DEFAULT_GITHUB_HOSTNAME = 'github.com';
+export const GITHUB_PROJECT_ANNOTATION = 'github.com/project-slug';

workspaces/scorecard/plugins/scorecard-backend-module-github/src/github/types.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export type GithubRepository = {
+  owner: string;
+  repo: string;
+};