You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc
+56-27Lines changed: 56 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,38 +5,47 @@
5
5
6
6
To achieve enhanced visibility and control over your software components, you must configure the GitHub Scorecards plugin to integrate GitHub metrics directly into your {product-very-short} catalog. This allows engineering teams to centralize development data, quickly identify risks, and accelerate decision-making related to component health and security.
7
7
8
-
To enable the GitHub metrics integration, you must create and configure a GitHub App to grant {product-very-short} access to the GitHub API.
8
+
To enable the GitHub metrics integration, you must create and configure an integration to grant {product-very-short} access to the GitHub API using either a https://docs.github.com/en/apps/overview[GitHub App] or a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token].
9
+
10
+
[IMPORTANT]
11
+
====
12
+
For long-lived integrations or when accessing resources on behalf of an organization, you must use a GitHub App.
13
+
====
9
14
10
15
.Prerequisites
11
16
12
17
* You have {install-category-link}[installed your {product-very-short} instance].
13
18
* You have {scorecard-plugin-book-link}#proc-installing-scorecard-plugin-in-rhdh-instance[installed the Scorecard images].
14
-
* You must have permissions in GitHub to create and manage a https://docs.github.com/en/apps/overview[GitHub App].
19
+
* Optional: If you choose the GitHub App option, you must have permissions in GitHub to create and manage a GitHub App.
15
20
* You must have {configuring-book-link}[added a custom {product-very-short} application configuration] and have enough permissions to change it.
16
21
17
22
.Procedure
18
23
To install and configure GitHub Scorecards in your {product-very-short} instance, complete the following steps:
19
24
20
-
. To allow {product-very-short} to access the GitHub API, you must create and configure a GitHub App and add the necessary integration to your configuration file:
21
-
.. Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories).
22
-
.. In the *General > Clients secrets* section, click *Generate a new client secret*.
23
-
.. In the *General > Private keys* section, click *Generate a private key*.
24
-
.. In the *Install App* tab, choose an account to install your GitHub App on.
25
-
.. Enter the following values and click *Save*:
26
-
*** *App ID*
27
-
*** *Client ID*
28
-
*** *Client Secret*
29
-
*** *Private key*
30
-
.. To add your GitHub credentials to {product-very-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets]. You can use these secrets in the {product-very-short} configuration files by using their respective environment variable names.
25
+
. Establish GitHub API access: Choose one of the following methods to grant {product-very-short} access to the GitHub API, and then complete the required configuration procedure:
26
+
** Configure using a GitHub App.
27
+
... Create a https://docs.github.com/en/apps/overview[GitHub App] with the required permissions (Read-only for Contents to allow reading repositories) to grant access to the GitHub API, and then complete the required configuration procedure:
31
28
+
32
-
`GITHUB_INTEGRATION_APP_ID`:: Enter the saved *App ID*.
33
-
`GITHUB_INTEGRATION_CLIENT_ID`:: Enter the saved *Client ID*.
34
-
`GITHUB_INTEGRATION_CLIENT_SECRET`:: Enter the saved *Client Secret*.
35
-
`GITHUB_INTEGRATION_HOST_DOMAIN`:: Enter the GitHub host doman: `github.com`
36
-
`GITHUB_INTEGRATION_ORGANIZATION`:: Enter your GitHub organization name, such as, `_<your_github_organization_name>_`
37
-
`GITHUB_INTEGRATION_PRIVATE_KEY_FILE`:: Enter the saved *Private key*.
38
-
39
-
. Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the `integrations.github` section:
29
+
[NOTE]
30
+
====
31
+
You must install the GitHub App on the organization (or user account) that owns repositories you want access to, granting it the necessary repository access permissions.
32
+
====
33
+
.... In the *General > Clients secrets* section, click *Generate a new client secret*.
34
+
.... In the *General > Private keys* section, click *Generate a private key*.
35
+
.... In the *Install App* tab, choose an account to install your GitHub App on.
36
+
.... Record the *App ID*, *Client ID*, *Client Secret*, and *Private key* values.
37
+
38
+
... Add secrets to {product-very-short} by adding the following key/value pairs to your
39
+
{configuring-book-link}#provisioning-your-custom-configuration[{product-very-short} secrets]. You can use these secrets in the {product-very-short} configuration files by using their respective environment variable names.
40
+
+
41
+
* `GITHUB_INTEGRATION_APP_ID`:: The saved *App ID*.
42
+
* `GITHUB_INTEGRATION_CLIENT_ID`:: The saved *Client ID*.
43
+
* `GITHUB_INTEGRATION_CLIENT_SECRET`:: The saved *Client Secret*.
44
+
* `GITHUB_INTEGRATION_HOST_DOMAIN`:: The GitHub host domain: `github.com`.
45
+
* `GITHUB_INTEGRATION_ORGANIZATION`:: Your GitHub organization name, such as `_<your_github_organization_name>_`.
46
+
* `GITHUB_INTEGRATION_PRIVATE_KEY_FILE`:: The saved *Private key* content.
47
+
48
+
... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the `integrations.github` section:
40
49
+
41
50
[source,yaml]
42
51
----
@@ -51,6 +60,29 @@ integrations:
51
60
${GITHUB_INTEGRATION_PRIVATE_KEY_FILE}
52
61
----
53
62
63
+
** Configure using a GitHub token.
64
+
... Create a https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub token] to grant {product-very-short} access to the GitHub API. Choose one of the following token types with these minimum permissions:
65
+
**** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic[Classic Personal Access Token] (PAT): Select the `repo` scope for read/write access to private repositories.
66
+
**** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token[Fine-Grained Personal Access Token] (PAT):
67
+
***** Choose the specific repositories that {product-very-short} must access.
68
+
***** Grant the token a **Read** permission for **Contents**.
69
+
70
+
... Add the token to {product-very-short} secrets by adding the following key/value pair to your {configuring-book-link}#provisioning-your-custom-configuration[{product-very-short} secrets].
71
+
+
72
+
where:
73
+
74
+
`GITHUB_TOKEN`:: The generated GitHub token.
75
+
76
+
... Configure the GitHub integration in your {product-very-short} `{my-app-config-file}` file by adding the streamlined `integrations.github` section:
77
+
+
78
+
[source,yaml]
79
+
----
80
+
integrations:
81
+
github:
82
+
- host: github.com
83
+
token: ${GITHUB_TOKEN}
84
+
----
85
+
54
86
. Install the GitHub Scorecard plugin by adding the following code to your {product-very-short} `dynamic-plugins-config.yaml` file:
55
87
+
56
88
[source,yaml]
@@ -60,7 +92,7 @@ plugins:
60
92
disabled: false
61
93
----
62
94
63
-
. To link a component to the GitHub data source, edit the `catalog-info.yaml` file for your {product-very-short} entity and add the required annotations as shown in the following code.
95
+
. Link a component to the GitHub data source by editing the `catalog-info.yaml` file for your {product-very-short} entity and adding the required annotations as shown in the following code:
64
96
+
65
97
[source,yaml]
66
98
----
@@ -90,7 +122,7 @@ where:
90
122
You must add the team entity to the Catalog to ensure the provided permissions are applicable.
91
123
====
92
124
93
-
. Statically ingest the catalog entity by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file that links to the `catalog-info.yaml` file:
125
+
. **Statically ingest the catalog entity** by adding the `catalog.locations` section in your {product-very-short} `{my-app-config-file}` file that links to the `catalog-info.yaml` file:
. (Optional) To customize the thresholds for the **GitHub Open Pull Requests** (`github.open_prs`) metric, add the following section to your {product-very-short} `{my-app-config-file}` file:
135
+
. (Optional) Customize the thresholds for the *GitHub Open Pull Requests* (`github.open_prs`) metric by adding the following section to your {product-very-short} `{my-app-config-file}` file:
104
136
+
105
137
[source,yaml]
106
138
----
@@ -121,6 +153,3 @@ scorecard:
121
153
where:
122
154
123
155
`scorecard:plugins:github:open_prs:thresholds`:: Lists the default threshold values for the GitHub open PRs metric.
124
-
125
-
.Additional resources
126
-
* {scorecard-plugin-book-link}#con-manage-metric-thresholds-in-scorecard-plugin_assembly-configuring-scorecards-in-rhdh[Managing metric thresholds in your Scorecard plugin]
0 commit comments