diff --git a/assemblies/assembly-authenticating-with-github.adoc b/assemblies/assembly-authenticating-with-github.adoc deleted file mode 100644 index 4d30cd3d36..0000000000 --- a/assemblies/assembly-authenticating-with-github.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="authenticating-with-github"] -= Authenticating with GitHub - -To authenticate users with GitHub or GitHub Enterprise: - -. xref:enabling-authentication-with-github[Enable the GitHub authentication provider in {product-short}]. -. xref:provisioning-users-from-github-to-the-software-catalog[Provision users from GitHub to the software catalog]. - -include::modules/authentication/proc-enabling-authentication-with-github.adoc[leveloffset=+1] - - -include::modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc[leveloffset=+1] - diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc index b1b4f77f86..f90c846dfe 100644 --- a/assemblies/assembly-enabling-authentication.adoc +++ b/assemblies/assembly-enabling-authentication.adoc @@ -13,7 +13,7 @@ include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1] include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1] -include::assembly-authenticating-with-github.adoc[leveloffset=+1] +include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1] include::assembly-authenticating-with-microsoft-azure.adoc[leveloffset=+1] diff --git a/assemblies/assembly-integrating-with-github.adoc b/assemblies/assembly-integrating-with-github.adoc new file mode 100644 index 0000000000..276fa4227a --- /dev/null +++ b/assemblies/assembly-integrating-with-github.adoc @@ -0,0 +1,8 @@ +[id='integrating-with-github'] += Integrating with GitHub in {product} + +include::modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc[leveloffset=+1] + + +include::assembly-bulk-importing-from-github.adoc[leveloffset=+1] + diff --git a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc index 8cd66db051..578f2b6637 100644 --- a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc +++ b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc @@ -7,8 +7,7 @@ include::../assembly-topology-plugin-configure.adoc[leveloffset=+1] include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] -include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] include::../assembly-using-servicenow.adoc[leveloffset=+1] -include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] \ No newline at end of file +include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index e8dc60f009..ee085c5f68 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -9,7 +9,7 @@ Catalog provider plugins handle this task asynchronously. These plugins query the Identity Provider (IdP) for relevant user and group information, and create or update corresponding entities in the {product-short} catalog. Scheduled provisioning ensures that the catalog accurately reflects the users and groups in your organization. -When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:authenticating-with-github[GitHub], or xref:assembly-authenticating-with-microsoft-azure[{azure-brand-name}]. +When a user attempts to access {product-short}, {product-short} redirects them to a configured authentication provider, such as xref:assembly-authenticating-with-rhbk[{rhbk-brand-name} ({rhbk})], xref:enabling-user-authentication-with-github[GitHub], or xref:assembly-authenticating-with-microsoft-azure[{azure-brand-name}]. This external IdP is responsible for authenticating the user. On successful authentication, the {product-short} authentication plugin, configured in your `{my-app-config-file}` file, processes the response from the IdP, resolves the identity in the {product-short} software catalog, and establishes a user session within {product-short}. diff --git a/modules/authentication/proc-enabling-authentication-with-github.adoc b/modules/authentication/proc-enabling-authentication-with-github.adoc deleted file mode 100644 index 2c9a0b1ca5..0000000000 --- a/modules/authentication/proc-enabling-authentication-with-github.adoc +++ /dev/null @@ -1,228 +0,0 @@ -[id="enabling-authentication-with-github"] -= Enabling authentication with GitHub - -To authenticate users with GitHub, enable the GitHub authentication provider in {product}. - -.Prerequisites -* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. -* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. - -.Procedure -. To allow {product-short} to authenticate with GitHub, create a GitHub App. -Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens. - -.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: -+ -* *GitHub App name*: Enter a unique name identifying your GitHub App, such as __<{product}>__-____. -* *Homepage URL*: Your {product-short} URL: `pass:c,a,q[{my-product-url}]`. -* *Authorization callback URL*: Your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. -* *Webhook URL*: Your {product-short} URL: `pass:c,a,q[{my-product-url}]`. -* *Webhook secret*: Provide a strong secret. -* *Repository permissions*: -** Enable `Read-only` access to: -*** *Administration* -*** *Commit statuses* -*** *Contents* -*** *Dependabot alerts* -*** *Deployments* -*** *Pull Requests* -*** *Webhooks* -+ -TIP: If you plan to make changes using the GitHub API, ensure that `Read and write` permissions are enabled instead of `Read-only`. - -** Toggle other permissions as per your needs. - -* *Organization permissions*: -** Enable `Read-only` access to *Members*. - -* For *Where can this GitHub App be installed?*, select `Only on this account`. - -.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. - -.. In the *General* -> *Private keys* section, click *Generate a private key*. - -.. In the *Install App* tab, choose an account to install your GitHub App on. - -.. Save the following values for the next step: - -* **App ID** -* **Client ID** -* **Client secret** -* **Private key** -* **Webhook secret** - -. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]: -+ -`AUTH_GITHUB_APP_ID`:: Enter the saved **App ID**. -`AUTH_GITHUB_CLIENT_ID`:: Enter the saved **Client ID**. -//`GITHUB_HOST_DOMAIN`:: Enter your GitHub host domain: `github.com` unless you are using GitHub Enterprise. -`GITHUB_ORGANIZATION`:: Enter your GitHub organization name, such as `____'. -`GITHUB_ORG_URL`:: Enter `$GITHUB_HOST_DOMAIN/$GITHUB_ORGANIZATION`. -`GITHUB_CLIENT_SECRET`:: Enter the saved **Client Secret**. -`GITHUB_PRIVATE_KEY_FILE`:: Enter the saved **Private key**. -`GITHUB_WEBHOOK_URL`:: Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. -`GITHUB_WEBHOOK_SECRET`:: Enter the saved *Webhook secret*. - -. . To set up the GitHub authentication provider and enable integration with the GitHub API in your {product-short} custom configuration, edit your custom {product-short} config map such as `{my-app-config-config-map}`, and add the following lines to the `{my-app-config-file}` file content: -+ -.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub -[source,yaml] ----- -auth: - environment: production # <1> - providers: - github: - production: - clientId: ${AUTH_GITHUB_CLIENT_ID} # <2> - clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} -integrations: - github: - - host: ${GITHUB_HOST_DOMAIN} - apps: - - appId: ${AUTH_GITHUB_APP_ID} - clientId: ${AUTH_GITHUB_CLIENT_ID} - clientSecret: ${GITHUB_CLIENT_SECRET} - webhookUrl: ${GITHUB_WEBHOOK_URL} - webhookSecret: ${GITHUB_WEBHOOK_SECRET} - privateKey: | - ${GITHUB_PRIVATE_KEY_FILE} -signInPage: github # <3> ----- -<1> Mark the environment as `production` and disable the Guest login option in the {product-short} login page. -<2> Apply the GitHub credentials configured in your {product-short} secrets. -<3> To enable the GitHub provider as your {product-short} sign-in provider. - -.. Optional: Consider adding the following optional fields: - -`callbackUrl`:: -The callback URL that GitHub uses when initiating an OAuth flow, such as: ____. -Define it when {product-short} is not the immediate receiver, such as in cases when you use one OAuth app for many {product-short} instances. -+ -.`{my-app-config-file}` file fragment with optional `enterpriseInstanceUrl` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - github: - production: - callbackUrl: ____ ----- - -//// -`enterpriseInstanceUrl`:: -Your GitHub Enterprise URL. -Requires you defined the `GITHUB_HOST_DOMAIN` secret in the previous step. -+ -.`{my-app-config-file}` file fragment with optional `enterpriseInstanceUrl` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - github: - production: - enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN} ----- -//// - -`sessionDuration`:: -Lifespan of the user session. -Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. -+ -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field -[source,yaml,subs="+quotes"] ----- -auth: - providers: - github: - production: - sessionDuration: { hours: 24 } ----- - -`signIn` :: - -`resolvers`::: -After successful authentication, the user signing in must be resolved to an existing user in the {product-short} catalog. To best match users securely for your use case, consider configuring a specific resolver. Enter the resolver list to override the default resolver: `usernameMatchingUserEntityName`. -+ -The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. -+ -WARNING: In production mode, only configure one resolver to ensure users are securely matched. - -`resolver`:::: -Enter the sign-in resolver name. -Available resolvers: - -* `usernameMatchingUserEntityName` -* `preferredUsernameMatchingUserEntityName` -* `emailMatchingUserEntityProfileEmail` - -`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: -Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. -+ -WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. -+ -.`{my-app-config-file}` file fragment with optional field to allow signing in users absent from the software catalog -[source,yaml] ----- -auth: - environment: production - providers: - github: - production: - clientId: ${AUTH_GITHUB_CLIENT_ID} - clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} - signIn: - resolvers: - - resolver: usernameMatchingUserEntityName - dangerouslyAllowSignInWithoutUserInCatalog: true -integrations: - github: - - host: ${GITHUB_HOST_DOMAIN} - apps: - - appId: ${AUTH_GITHUB_APP_ID} - clientId: ${AUTH_GITHUB_CLIENT_ID} - clientSecret: ${GITHUB_CLIENT_SECRET} - webhookUrl: ${GITHUB_WEBHOOK_URL} - webhookSecret: ${GITHUB_WEBHOOK_SECRET} - privateKey: | - ${GITHUB_PRIVATE_KEY_FILE} -signInPage: github ----- - -[TIP] -==== -To enable GitHub integration with a different authentication provider, complete the following configurations: - -* Add the GitHub provider to the existing `auth` section. -* Keep the `signInPage` section from your authentication provider configuration. - -.`{my-app-config-file}` file fragment with mandatory fields to enable GitHub integration and use a different authentication provider -[source,yaml,subs="+quotes"] ----- -auth: - environment: production - providers: - github: - production: - clientId: ${AUTH_GITHUB_CLIENT_ID} - clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} - ____ -integrations: - github: - - host: ${GITHUB_HOST_DOMAIN} - apps: - - appId: ${AUTH_GITHUB_APP_ID} - clientId: ${AUTH_GITHUB_CLIENT_ID} - clientSecret: ${GITHUB_CLIENT_SECRET} - webhookUrl: ${GITHUB_WEBHOOK_URL} - webhookSecret: ${GITHUB_WEBHOOK_SECRET} - privateKey: | - ${GITHUB_PRIVATE_KEY_FILE} -signInPage: ____ ----- -==== - -.Verification -. Go to the {product-short} login page. -. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled. -. Log in with GitHub. - diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc new file mode 100644 index 0000000000..e2f6fa65ea --- /dev/null +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -0,0 +1,209 @@ +[id="enabling-user-authentication-with-github"] += Enabling user authentication with GitHub + +To authenticate users with GitHub, configure the GitHub authentication provider in {product} and provision the users and groups from GitHub to the {product-short} software catalog. + +.Prerequisites +* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. + +* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. +Alternatively, you can ask your GitHub administrator to prepare the required GitHub App. + +.Procedure +. To allow {product-short} to authenticate with GitHub, create a GitHub App. +Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens. + +.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: + +GitHub App name:: +Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-____`. + +Homepage URL:: +Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. + +Authorization callback URL:: +Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. + +Webhook:: +Clear "Active", as this is not needed for authentication and catalog providers. + +Organization permissions:: +Enable `Read-only` access to *Members*. + +Where can this GitHub App be installed?:: +Select `Only on this account`. + +.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. + +.. In the *Install App* tab, choose an account to install your GitHub App on. + +.. Save the following values for the next step: + +* **Client ID** +* **Client secret** + +. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]. +You can use these secrets in the {product-short} configuration files by using their respective environment variable name. + +`AUTHENTICATION_GITHUB_CLIENT_ID`:: +Enter the saved **Client ID**. + +`AUTHENTICATION_GITHUB_CLIENT_SECRET`:: +Enter the saved **Client Secret**. + +`AUTHENTICATION_GITHUB_HOST_DOMAIN`:: +Enter the GitHub host domain: `github.com`. + +`AUTHENTICATION_GITHUB_ORGANIZATION`:: +Enter your GitHub organization name, such as `____`. + +. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`). +This plugin ingests GitHub users and groups to the {product-short} software catalog. ++ +.`dynamic-plugins.yaml` file fragment +[code,yaml] +---- +plugins: + - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org' + disabled: false +---- + +. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: ++ +-- +[id=githubProviderId] +.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields +[source,yaml] +---- +catalog: + providers: + githubOrg: + id: githuborg + githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}" + orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ] + schedule: + frequency: + minutes: 30 + initialDelay: + seconds: 15 + timeout: + minutes: 15 +---- + +`id`:: +Enter a stable identifier for this provider, such as `githuborg`. +Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts. + +`githubUrl`:: +Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`. + +`orgs`:: +Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`. + +`schedule.frequency`:: +Enter your schedule frequency, in the cron, ISO duration, or "human duration" format. + +`schedule.timeout`:: +Enter your schedule timeout, in the ISO duration or "human duration" format. + +`schedule.initialDelay`:: +Enter your schedule initial delay, in the ISO duration or "human duration" format. +-- + +. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content: ++ +-- +.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub +[source,yaml] +---- +auth: + environment: production + providers: + github: + production: + clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} + clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} +signInPage: github +---- + +`environment`:: +Enter `production` to disable the Guest login option in the {product-short} login page. + +`clientId`:: +Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_ID}`. + +`clientSecret`:: +Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_SECRET}`. + +`signInPage`:: +Enter `github` to enable the GitHub provider as your {product-short} sign-in provider. + +Optional: Consider adding the following optional fields: + +.`{my-app-config-file}` file fragment including optional fields to enable authentication with GitHub +[source,yaml,subs="+quotes"] +---- +auth: + environment: production + providers: + github: + production: + clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} + clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} + callbackUrl: ____ + sessionDuration: { hours: 24 } + signIn: + resolvers: + - resolver: usernameMatchingUserEntityName + dangerouslyAllowSignInWithoutUserInCatalog: true +signInPage: github +---- + +`callbackUrl`:: +Enter the callback URL that GitHub uses when initiating an OAuth flow, such as: ____. +Define it when {product-short} is not the immediate receiver, such as in cases when you use one OAuth app for many {product-short} instances. + +`sessionDuration`:: +Enter the user session lifespan, in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration". + +`signIn`:: + +`resolvers`::: +After successful authentication, {product-short} resolves the user signing in to an existing user in the {product-short} catalog. +To best match users securely for your use case, consider configuring a specific resolver. ++ +Enter the resolver list to override the default resolver: `usernameMatchingUserEntityName`. ++ +The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. ++ +WARNING: In production mode, only configure one resolver to ensure users are securely matched. + +`resolver`:::: +Enter the sign-in resolver name. +Available resolvers: + +* `usernameMatchingUserEntityName` +* `preferredUsernameMatchingUserEntityName` +* `emailMatchingUserEntityProfileEmail` + +`dangerouslyAllowSignInWithoutUserInCatalog: true`:::: +Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. ++ +WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. +-- + +.Verification +. To verify user and group provisioning, check the console logs. ++ +.Successful synchronization example: +[source,json] +---- +{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"} +{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"} +---- + +. To verify GitHub authentication: +.. Go to the {product-short} login page. +.. Your {product-short} sign-in page displays *Sign in using GitHub* and the Guest user sign-in is disabled. +.. Log in with a GitHub account. + diff --git a/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc b/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc deleted file mode 100644 index 010e812203..0000000000 --- a/modules/authentication/proc-provisioning-users-from-github-to-the-software-catalog.adoc +++ /dev/null @@ -1,81 +0,0 @@ -[id="provisioning-users-from-github-to-the-software-catalog"] -= Provisioning users from GitHub to the software catalog - -To authenticate users, {product} requires their presence in the software catalog. -Consider configuring {product-short} to provision users from GitHub to the software catalog on schedule, rather than provisioning the users manually. - -.Prerequisites -* You have xref:enabling-authentication-with-github[enabled authentication with GitHub], including the following secrets: -** `GITHUB_HOST_DOMAIN` -** `GITHUB_ORGANIZATION` - -.Procedure -. link:{installing-and-viewing-plugins-book-url}[Enable the `backstage-plugin-catalog-backend-module-github-dynamic` plugin]. -+ -.`dynamic-plugins.yaml` file fragment -[code,yaml] ----- -plugins: - - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic' - disabled: false ----- - -. To enable GitHub member discovery, edit `{my-app-config-file}`, your custom {product-short} configuration file: -+ --- -[id=githubProviderId] -.`{my-app-config-file}` fragment with mandatory `github` fields -[source,yaml] ----- -catalog: - providers: - github: - providerId: - organization: "${GITHUB_ORGANIZATION}" - schedule: - frequency: - minutes: 30 - initialDelay: - seconds: 15 - timeout: - minutes: 15 - githubOrg: - githubUrl: "${GITHUB_HOST_DOMAIN}" - orgs: [ "${GITHUB_ORGANIZATION}" ] - schedule: - frequency: - minutes: 30 - initialDelay: - seconds: 15 - timeout: - minutes: 15 ----- - -`organization`, `githubUrl`, and `orgs`:: -Use the {product-short} application information that you have created in GitHub and configured in OpenShift as secrets. - -`schedule.frequency`:: -To specify custom schedule frequency. -Supports cron, ISO duration, and "human duration" as used in code. - -`schedule.timeout`:: -To specify custom timeout. -Supports ISO duration and "human duration" as used in code. - -`schedule.initialDelay`:: -To specify custom initial delay. -Supports ISO duration and "human duration" as used in code. --- - -.Verification -. Check the console logs to verify that the synchronization is completed. -+ -.Successful synchronization example: -[source,json] ----- -{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:production:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"} -{"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:production:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"} ----- - -. Log in with a GitHub account. - diff --git a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc index bf1498043e..6164598f86 100644 --- a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc +++ b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-customization-service.adoc @@ -6,7 +6,7 @@ You can even use a different service for each page. .Prerequisites * You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `{my-app-config-file}` file. -For example, to configure GitHub as an integration, see link:{authentication-book-url}#authenticating-with-github[Authenticating with GitHub]. +For example, to configure GitHub as an integration, see link:{authentication-book-url}#enabling-user-authentication-with-github[Authenticating with GitHub]. * You have enabled the `./dynamic-plugins/dist/backstage-community-plugin-tech-radar` and `/dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` plugins. diff --git a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc index 697d3111b5..acc3ff2e96 100644 --- a/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc +++ b/modules/customizing-the-tech-radar-page/proc-customizing-the-tech-radar-page-by-using-a-json-file.adoc @@ -5,7 +5,7 @@ For ease of use and simplicity, you can configure the Tech Radar page by using a .Prerequisites -* You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `{my-app-config-file}` file. For example, to configure GitHub as an integration, see link:{authentication-book-url}#authenticating-with-github[Authenticating with GitHub]. +* You have specified the data sources for the Tech Radar plugin in the `integrations` section of the `{my-app-config-file}` file. For example, to configure GitHub as an integration, see link:{authentication-book-url}#enabling-user-authentication-with-github[Authenticating with GitHub]. * You have enabled the `./dynamic-plugins/dist/backstage-community-plugin-tech-radar` and `/dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` plugins. diff --git a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc new file mode 100644 index 0000000000..de0ff31dcf --- /dev/null +++ b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc @@ -0,0 +1,154 @@ +[id="enabling-github-repository-discovery"] += Enabling GitHub repository discovery + +Consider configuring {product-short} to discover and ingest your GitHub repositories automatically. +If a repository contains a `catalog-info.yaml` file, {product-short} ingests the repository into the catalog as a component. + +.Prerequisites +* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. + +* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. + +.Procedure +. To allow {product-short} to access the GitHub API, create a GitHub App. +Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens. + +.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: + +GitHub App name:: +Enter a unique name identifying your GitHub App, such as `integrating-with-rhdh-____`. + +Homepage URL:: +Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. + +Authorization callback URL:: +Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. + +Webhook:: +Clear "Active", as this is not needed for authentication and catalog providers. + +App permissions:: +Select permissions to define the level of access for the app. +Adapt permissions to your needs: + +Reading software components::: + +Contents:::: +`Read-only` + +Commit statuses:::: +`Read-only` + +Reading organization data::: + +Members:::: +`Read-only` + +Publishing software templates::: +Set permissions if you intend to use the same GitHub App for software templates. + +Administration:::: +`Read & write` (for creating repositories) + +Contents:::: +`Read & write` + +Metadata:::: +`Read-only` + +Pull requests:::: +`Read & write` + +Issues:::: +`Read & write` + +Workflows:::: +`Read & write` (if templates include GitHub workflows) + +Variables:::: +`Read & write` (if templates include GitHub Action Repository Variables) + +Secrets:::: +`Read & write` (if templates include GitHub Action Repository Secrets) + +Environments:::: +`Read & write` (if templates include GitHub Environments) + +Organization permissions:: +Members::: +`Read-only` + +Where can this GitHub App be installed?:: +Select `Only on this account`. + +.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. + +.. In the *General* -> *Private keys* section, click *Generate a private key*. + +.. In the *Install App* tab, choose an account to install your GitHub App on. + +.. Save the following values for the next step: + +* **App ID** +* **Client ID** +* **Client secret** +* **Private key** + +. To add your GitHub credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets]. +You can use these secrets in the {product-short} configuration files by using their respective environment variable name. + +`GITHUB_INTEGRATION_APP_ID`:: +Enter the saved **App ID**. +`GITHUB_INTEGRATION_CLIENT_ID`:: +Enter the saved **Client ID**. +`GITHUB_INTEGRATION_CLIENT_SECRET`:: +Enter the saved **Client Secret**. +`GITHUB_INTEGRATION_HOST_DOMAIN`:: +Enter the GitHub host domain: `github.com`. +`GITHUB_INTEGRATION_ORGANIZATION`:: +Enter your GitHub organization name, such as `____'. +`GITHUB_INTEGRATION_PRIVATE_KEY_FILE`:: +Enter the saved **Private key**. + +. Enable the `plugin-catalog-backend-module-github` plugin in your `dynamic-plugins.yaml` file. ++ +This plugin discovers catalog entities by scanning repositories within a GitHub organization for `catalog-info.yaml` files. +It provides an automated alternative to manually registering components via `catalog.locations`. +When a repository contains a `catalog-info.yaml` file, the entity is ingested into the catalog as a component. ++ +.`dynamic-plugins.yaml` file fragment +[code,yaml] +---- +plugins: + - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github' + disabled: false +---- + +. Configure the GitHub integration, by adding the `catalog.providers.github` and the `integrations.github` sections to your custom {product-short} `{my-app-config-file}` configuration file: ++ +.`{my-app-config-file}` file fragment with mandatory fields to enable GitHub integration +[source,yaml,subs="+quotes"] +---- +catalog: + providers: + github: + providerId: + organization: "${GITHUB_INTEGRATION_ORGANIZATION}" + schedule: + frequency: + minutes: 30 + initialDelay: + seconds: 15 + timeout: + minutes: 15 +integrations: + github: + - host: ${GITHUB_INTEGRATION_HOST_DOMAIN} + apps: + - appId: ${GITHUB_INTEGRATION_APP_ID} + clientId: ${GITHUB_INTEGRATION_CLIENT_ID} + clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET} + privateKey: | + ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE} +---- + diff --git a/titles/integrating-with-github/artifacts b/titles/integrating-with-github/artifacts new file mode 120000 index 0000000000..04f3a24af5 --- /dev/null +++ b/titles/integrating-with-github/artifacts @@ -0,0 +1 @@ +../../artifacts/ \ No newline at end of file diff --git a/titles/integrating-with-github/assemblies b/titles/integrating-with-github/assemblies new file mode 120000 index 0000000000..51bb510220 --- /dev/null +++ b/titles/integrating-with-github/assemblies @@ -0,0 +1 @@ +../../assemblies/ \ No newline at end of file diff --git a/titles/integrating-with-github/docinfo.xml b/titles/integrating-with-github/docinfo.xml new file mode 100644 index 0000000000..5f7fe2ebac --- /dev/null +++ b/titles/integrating-with-github/docinfo.xml @@ -0,0 +1,11 @@ +{title} +{product} +{product-version} +{subtitle} + + {abstract} + + + {company-name} Customer Content Services + + diff --git a/titles/integrating-with-github/images b/titles/integrating-with-github/images new file mode 120000 index 0000000000..847b03ed05 --- /dev/null +++ b/titles/integrating-with-github/images @@ -0,0 +1 @@ +../../images/ \ No newline at end of file diff --git a/titles/integrating-with-github/master.adoc b/titles/integrating-with-github/master.adoc new file mode 100644 index 0000000000..78f1d0b5b0 --- /dev/null +++ b/titles/integrating-with-github/master.adoc @@ -0,0 +1,12 @@ +include::artifacts/attributes.adoc[] +:context: title-integrating-with-github +:imagesdir: images +:title: Integrating {product} with GitHub +:subtitle: Configuring integration to the GitHub Git provider in {product} +:abstract: As a {product} platform engineer, you can integrate {product} with the GitHub Git provider. +//[id="{context}"] +//= {title} + +//{abstract} + +include::assemblies/assembly-integrating-with-github.adoc[] diff --git a/titles/integrating-with-github/modules b/titles/integrating-with-github/modules new file mode 120000 index 0000000000..36719b9de7 --- /dev/null +++ b/titles/integrating-with-github/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file