fix: better error around github teams not found

Adds a literate error around the
`createGithubRepoWithCollaboratorsAndTopics` function in order to
provide that error in the scaffolder logs. Prior to this, the only thing
returned was "Not Found," which didn't provide much information for
someone trying to determine what failed in the background.

Fixes #10160

Signed-off-by: Christopher Kruse <ckruse@flexport.com>

.changeset/olive-ads-peel.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Provide better error messaging when GitHub fails due to missing team definitions

plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/helpers.ts

@@ -190,13 +190,22 @@ export async function createGithubRepoWithCollaboratorsAndTopics(
 
   if (access?.startsWith(`${owner}/`)) {
     const [, team] = access.split('/');
-    await client.rest.teams.addOrUpdateRepoPermissionsInOrg({
-      org: owner,
-      team_slug: team,
-      owner,
-      repo,
-      permission: 'admin',
-    });
+    try {
+      await client.rest.teams.addOrUpdateRepoPermissionsInOrg({
+        org: owner,
+        team_slug: team,
+        owner,
+        repo,
+        permission: 'admin',
+      });
+    } catch (e) {
+      if (e.data.message === 'Not Found') {
+        const message = `Received 'Not Found' from the API; one of org:
+        ${owner}, team: ${team} or repo: ${repo} was not found within GitHub.`;
+        logger.warn(message);
+        throw new Error(message, { cause: e });
+      }
+    }
     // No need to add access if it's the person who owns the personal account
   } else if (access && access !== owner) {
     await client.rest.repos.addCollaborator({

plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/github.test.ts

@@ -518,6 +518,31 @@ describe('publish:github', () => {
     });
   });
 
+  it('should provide an adequate failure message when adding access', async () => {
+    mockOctokit.rest.users.getByUsername.mockResolvedValue({
+      data: { type: 'User' },
+    });
+
+    mockOctokit.rest.repos.createForAuthenticatedUser.mockResolvedValue({
+      data: {
+        clone_url: 'https://github.com/clone/url.git',
+        html_url: 'https://github.com/html/url',
+      },
+    });
+
+    mockOctokit.rest.teams.addOrUpdateRepoPermissionsInOrg.mockRejectedValue({
+      status: 404,
+      data: {
+        message: 'Not Found',
+        documentation_url:
+          'https://docs.github.com/en/rest/teams/teams#add-or-update-team-repository-permissions',
+      },
+    });
+    await expect(action.handler(mockContext)).rejects.toThrow(
+      "Received 'Not Found' from the API;",
+    );
+  });
+
   it('should add outside collaborators when provided', async () => {
     mockOctokit.rest.users.getByUsername.mockResolvedValue({
       data: { type: 'User' },