integration-react: review fixes for ScmAuth

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/great-rabbits-juggle.md

@@ -2,4 +2,35 @@
 '@backstage/plugin-catalog-import': minor
 ---
 
-Switched to using the `ScmAuthApi` for authentication rather than GitHub auth. If you are instantiating your `CatalogImportClient` manually you now need to pass in an instance of `ScmAuthApi` instead. Also be sure to register the `scmAuthApiRef` from the `@backstage/integration-react` in your app.
+Switched to using the `ScmAuthApi` for authentication rather than GitHub auth. If you are instantiating your `CatalogImportClient` manually you now need to pass in an instance of `ScmAuthApi` instead.
+
+Also be sure to register the `scmAuthApiRef` from the `@backstage/integration-react` in your app:
+
+```ts
+import { ScmAuth } from '@backstage/integration-react';
+
+// in packages/app/apis.ts
+
+const apis = [
+// ... other APIs
+
+ScmAuth.createDefaultApiFactory();
+
+// OR
+
+createApiFactory({
+  api: scmAuthApiRef,
+  deps: {
+    gheAuthApi: gheAuthApiRef,
+    githubAuthApi: githubAuthApiRef,
+  },
+  factory: ({ githubAuthApi, gheAuthApi }) =>
+    ScmAuth.merge(
+      ScmAuth.forGithub(githubAuthApi),
+      ScmAuth.forGithub(gheAuthApi, {
+        host: 'ghe.example.com',
+      }),
+    ),
+});
+]
+```

.changeset/purple-scissors-allow.md

@@ -42,3 +42,48 @@ createApiFactory({
     ),
 });
 ```
+
+The additional `gheAuthApiRef` utility API can be defined either inside the app itself if it's only used for this purpose, for inside an internal common package for APIs, such as `@internal/apis`:
+
+```ts
+const gheAuthApiRef: ApiRef<OAuthApi & ProfileInfoApi & SessionApi> =
+  createApiRef({
+    id: 'internal.auth.ghe',
+  });
+```
+
+And then implemented using the `GithubAuth` class from `@backstage/core-app-api`:
+
+```ts
+createApiFactory({
+  api: githubAuthApiRef,
+  deps: {
+    discoveryApi: discoveryApiRef,
+    oauthRequestApi: oauthRequestApiRef,
+    configApi: configApiRef,
+  },
+  factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
+    GithubAuth.create({
+      provider: {
+        id: 'ghe',
+        icon: ...,
+        title: 'GHE'
+      },
+      discoveryApi,
+      oauthRequestApi,
+      defaultScopes: ['read:user'],
+      environment: configApi.getOptionalString('auth.environment'),
+    }),
+})
+```
+
+Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID `ghe`:
+
+```ts
+// Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts
+providerFactories: {
+  ghe: createGithubProvider(),
+},
+```
+
+Other providers follow the same steps, but you will want to use the appropriate auth API implementation in the frontend, such as for example `GitlabAuth`.

packages/integration-react/src/api/ScmAuth.ts

@@ -36,7 +36,7 @@ type ScopeMapping = {
 };
 
 class ScmAuthMux implements ScmAuthApi {
-  #providers = new Array<ScmAuth>();
+  #providers: Array<ScmAuth>;
 
   constructor(providers: ScmAuth[]) {
     this.#providers = providers;

packages/integration-react/src/api/ScmAuthApi.ts

@@ -59,7 +59,7 @@ export interface ScmAuthTokenResponse {
 /**
  * ScmAuthApi provides methods for authenticating towards source code management services.
  *
- * As opposed to using the using the GitHub, GitLab and other auth APIs
+ * As opposed to using the GitHub, GitLab and other auth APIs
  * directly, this API allows for more generic access to SCM services.
  *
  * @public