Create GitHub teams in the background of Org requests (#338)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Refactor**
* Organization GitHub team creation now runs asynchronously via a queued
background flow (batched dispatch and worker processing).
* Team creation responses now indicate whether a team was newly created
or already existed (returns id plus updated flag).

* **Chores**
  * Updated lock/Redis utility dependency to a newer patch version.

* **Tests**
* Added comprehensive unit tests for the new queued team-creation
handler and updated tests for the changed return shape.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: devksingh4

src/api/functions/github.ts

@@ -152,7 +152,7 @@ export async function createGithubTeam({
 
     if (existingTeam) {
       logger.info(`Team "${name}" already exists with id: ${existingTeam.id}`);
-      return existingTeam.id;
+      return { updated: false, id: existingTeam.id };
     }
     logger.info(`Creating GitHub team "${name}"`);
     const response = await octokit.request("POST /orgs/{org}/teams", {
@@ -196,7 +196,7 @@ export async function createGithubTeam({
       logger.warn(`Failed to remove user from team ${newTeamId}:`, removeError);
     }
 
-    return newTeamId;
+    return { updated: true, id: newTeamId };
   } catch (e) {
     if (e instanceof BaseError) {
       throw e;

src/api/package.json

@@ -57,7 +57,7 @@
     "pino": "^9.6.0",
     "pluralize": "^8.0.0",
     "qrcode": "^1.5.4",
-    "redlock-universal": "^0.6.0",
+    "redlock-universal": "^0.6.4",
     "sanitize-html": "^2.17.0",
     "stripe": "^18.0.0",
     "uuid": "^11.1.0",
@@ -74,4 +74,4 @@
     "pino-pretty": "^13.1.1",
     "yaml": "^2.8.1"
   }
-}
+}

src/api/routes/organizations.ts

@@ -53,14 +53,15 @@ import {
 } from "api/functions/entraId.js";
 import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
 import { getRoleCredentials } from "api/functions/sts.js";
-import { SQSClient } from "@aws-sdk/client-sqs";
+import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
 import { sendSqsMessagesInBatches } from "api/functions/sqs.js";
 import { retryDynamoTransactionWithBackoff } from "api/utils.js";
 import {
   assignIdpGroupsToTeam,
   createGithubTeam,
 } from "api/functions/github.js";
 import { SKIP_EXTERNAL_ORG_LEAD_UPDATE } from "common/overrides.js";
+import { AvailableSQSFunctions, SQSPayload } from "common/types/sqsMessage.js";
 
 export const CLIENT_HTTP_CACHE_POLICY = `public, max-age=${ORG_DATA_CACHED_DURATION}, stale-while-revalidate=${Math.floor(ORG_DATA_CACHED_DURATION * 1.1)}, stale-if-error=3600`;
 
@@ -413,12 +414,10 @@ const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
         ? (unmarshall(metadataResponse.Item).leadsEntraGroupId as string)
         : undefined;
 
-      let githubTeamId = metadataResponse.Item
-        ? (unmarshall(metadataResponse.Item).githubTeamId as number)
+      const githubTeamId = metadataResponse.Item
+        ? (unmarshall(metadataResponse.Item).leadsGithubTeamId as number)
         : undefined;
 
-      let createdGithubTeam = false;
-
       const entraIdToken = await getEntraIdToken({
         clients,
         clientId: fastify.environmentConfig.AadValidClientId,
@@ -428,8 +427,6 @@ const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
 
       const shouldCreateNewEntraGroup =
         !entraGroupId && !shouldSkipEnhancedActions;
-      const shouldCreateNewGithubGroup =
-        !githubTeamId && !shouldSkipEnhancedActions;
       const grpDisplayName = `${request.params.orgId} Admin`;
       const orgInfo = getOrgByName(request.params.orgId);
       if (!orgInfo) {
@@ -524,65 +521,6 @@ const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
         }
       }
 
-      // Create GitHub team if needed
-      if (shouldCreateNewGithubGroup) {
-        request.log.info(
-          `No GitHub team exists for ${request.params.orgId}. Creating new team...`,
-        );
-        const suffix = fastify.environmentConfig.GroupEmailSuffix;
-        githubTeamId = await createGithubTeam({
-          orgId: fastify.environmentConfig.GithubOrgName,
-          githubToken: fastify.secretConfig.github_pat,
-          parentTeamId: fastify.environmentConfig.ExecGithubTeam,
-          name: `${grpShortName}${suffix === "" ? "" : `-${suffix}`}`,
-          description: grpDisplayName,
-          logger: request.log,
-        });
-        request.log.info(
-          `Created GitHub team "${githubTeamId}" for ${request.params.orgId} leads.`,
-        );
-        createdGithubTeam = true;
-
-        // Store GitHub team ID immediately
-        const logStatement = buildAuditLogTransactPut({
-          entry: {
-            module: Modules.ORG_INFO,
-            message: `Created GitHub team "${githubTeamId}" for organization leads.`,
-            actor: request.username!,
-            target: request.params.orgId,
-          },
-        });
-
-        const storeGithubIdOperation = async () => {
-          const commandTransaction = new TransactWriteItemsCommand({
-            TransactItems: [
-              ...(logStatement ? [logStatement] : []),
-              {
-                Update: {
-                  TableName: genericConfig.SigInfoTableName,
-                  Key: marshall({
-                    primaryKey: `DEFINE#${request.params.orgId}`,
-                    entryId: "0",
-                  }),
-                  UpdateExpression:
-                    "SET leadsGithubTeamId = :githubTeamId, updatedAt = :updatedAt",
-                  ExpressionAttributeValues: marshall({
-                    ":githubTeamId": githubTeamId,
-                    ":updatedAt": new Date().toISOString(),
-                  }),
-                },
-              },
-            ],
-          });
-          return await clients.dynamoClient.send(commandTransaction);
-        };
-
-        await retryDynamoTransactionWithBackoff(
-          storeGithubIdOperation,
-          request.log,
-          `Store GitHub team ID for ${request.params.orgId}`,
-        );
-      }
       const commonArgs = {
         orgId: request.params.orgId,
         actorUsername: request.username!,
@@ -628,36 +566,37 @@ const organizationsPlugin: FastifyPluginAsync = async (fastify, _options) => {
         .map((r) => r.value)
         .filter((p): p is SQSMessage => p !== null);
 
+      if (!fastify.sqsClient) {
+        fastify.sqsClient = new SQSClient({
+          region: genericConfig.AwsRegion,
+        });
+      }
+
+      // Queue creating GitHub team if needed
+      if (!githubTeamId) {
+        const sqsPayload: SQSPayload<AvailableSQSFunctions.CreateOrgGithubTeam> =
+          {
+            function: AvailableSQSFunctions.CreateOrgGithubTeam,
+            metadata: {
+              initiator: request.username!,
+              reqId: request.id,
+            },
+            payload: {
+              orgName: request.params.orgId,
+              githubTeamDescription: grpDisplayName,
+              githubTeamName: grpShortName,
+            },
+          };
+        sqsPayloads.push(sqsPayload);
+      }
       if (sqsPayloads.length > 0) {
-        if (!fastify.sqsClient) {
-          fastify.sqsClient = new SQSClient({
-            region: genericConfig.AwsRegion,
-          });
-        }
         await sendSqsMessagesInBatches({
           sqsClient: fastify.sqsClient,
           queueUrl: fastify.environmentConfig.SqsQueueUrl,
           logger: request.log,
           sqsPayloads,
         });
       }
-
-      if (
-        createdGithubTeam &&
-        githubTeamId &&
-        fastify.environmentConfig.GithubIdpSyncEnabled
-      ) {
-        request.log.info("Setting up IDP sync for Github team!");
-        await assignIdpGroupsToTeam({
-          githubToken: fastify.secretConfig.github_pat,
-          teamId: githubTeamId,
-          logger: request.log,
-          groupsToSync: [entraGroupId].filter((x): x is string => !!x),
-          orgId: fastify.environmentConfig.GithubOrgId,
-          orgName: fastify.environmentConfig.GithubOrgName,
-        });
-      }
-
       return reply.status(201).send();
     },
   );

src/api/sqs/handlers/createOrgGithubTeam.ts

@@ -0,0 +1,169 @@
+import { AvailableSQSFunctions } from "common/types/sqsMessage.js";
+import { currentEnvironmentConfig, SQSHandlerFunction } from "../index.js";
+import {
+  DynamoDBClient,
+  GetItemCommand,
+  TransactWriteItemsCommand,
+} from "@aws-sdk/client-dynamodb";
+import { genericConfig, SecretConfig } from "common/config.js";
+import { getSecretConfig } from "../utils.js";
+import RedisModule from "ioredis";
+import { createLock, IoredisAdapter } from "redlock-universal";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import { InternalServerError } from "common/errors/index.js";
+import {
+  assignIdpGroupsToTeam,
+  createGithubTeam,
+} from "api/functions/github.js";
+import { buildAuditLogTransactPut } from "api/functions/auditLog.js";
+import { Modules } from "common/modules.js";
+import { retryDynamoTransactionWithBackoff } from "api/utils.js";
+import { SKIP_EXTERNAL_ORG_LEAD_UPDATE } from "common/overrides.js";
+import { getOrgByName } from "@acm-uiuc/js-shared";
+
+export const createOrgGithubTeamHandler: SQSHandlerFunction<
+  AvailableSQSFunctions.CreateOrgGithubTeam
+> = async (payload, metadata, logger) => {
+  const secretConfig: SecretConfig = await getSecretConfig({
+    logger,
+    commonConfig: { region: genericConfig.AwsRegion },
+  });
+  const redisClient = new RedisModule.default(secretConfig.redis_url);
+  try {
+    const { orgName, githubTeamName, githubTeamDescription } = payload;
+    const orgImmutableId = getOrgByName(orgName)!.id;
+    if (SKIP_EXTERNAL_ORG_LEAD_UPDATE.includes(orgImmutableId)) {
+      logger.info(
+        `Organization ${orgName} has external updates disabled, exiting.`,
+      );
+      return;
+    }
+    const dynamo = new DynamoDBClient({
+      region: genericConfig.AwsRegion,
+    });
+    const lock = createLock({
+      adapter: new IoredisAdapter(redisClient),
+      key: `createOrgGithubTeamHandler:${orgImmutableId}`,
+      retryAttempts: 5,
+      retryDelay: 300,
+    });
+    return await lock.using(async (signal) => {
+      const getMetadataCommand = new GetItemCommand({
+        TableName: genericConfig.SigInfoTableName,
+        Key: marshall({
+          primaryKey: `DEFINE#${orgName}`,
+          entryId: "0",
+        }),
+        ProjectionExpression: "#entra,#gh",
+        ExpressionAttributeNames: {
+          "#entra": "leadsEntraGroupId",
+          "#gh": "leadsGithubTeamId",
+        },
+        ConsistentRead: true,
+      });
+      const existingData = await dynamo.send(getMetadataCommand);
+      if (!existingData || !existingData.Item) {
+        throw new InternalServerError({
+          message: `Could not find org entry for ${orgName}`,
+        });
+      }
+      const currentOrgInfo = unmarshall(existingData.Item) as {
+        leadsEntraGroupId?: string;
+        leadsGithubTeamId?: string;
+      };
+      if (!currentOrgInfo.leadsEntraGroupId) {
+        logger.info(`${orgName} does not have an Entra group, skipping!`);
+        return;
+      }
+      if (currentOrgInfo.leadsGithubTeamId) {
+        logger.info("This org already has a GitHub team, skipping");
+        return;
+      }
+      if (signal.aborted) {
+        throw new InternalServerError({
+          message:
+            "Checked on lock before creating GitHub team, we've lost the lock!",
+        });
+      }
+      logger.info(`Creating GitHub team for ${orgName}!`);
+      const suffix = currentEnvironmentConfig.GroupEmailSuffix;
+      const finalName = `${githubTeamName}${suffix === "" ? "" : `-${suffix}`}`;
+      const { updated, id: teamId } = await createGithubTeam({
+        orgId: currentEnvironmentConfig.GithubOrgName,
+        githubToken: secretConfig.github_pat,
+        parentTeamId: currentEnvironmentConfig.ExecGithubTeam,
+        name: finalName,
+        description: githubTeamDescription,
+        logger,
+      });
+      if (!updated) {
+        logger.info(
+          `Github team "${finalName}" already existed. We're assuming team sync was already set up (if not, please configure manually).`,
+        );
+      } else {
+        logger.info(
+          `Github team "${finalName}" created with team ID "${teamId}".`,
+        );
+        if (currentEnvironmentConfig.GithubIdpSyncEnabled) {
+          logger.info(
+            `Setting up IDP sync for Github team from Entra ID group ${currentOrgInfo.leadsEntraGroupId}`,
+          );
+          await assignIdpGroupsToTeam({
+            githubToken: secretConfig.github_pat,
+            teamId,
+            logger,
+            groupsToSync: [currentOrgInfo.leadsEntraGroupId],
+            orgId: currentEnvironmentConfig.GithubOrgId,
+            orgName: currentEnvironmentConfig.GithubOrgName,
+          });
+        }
+      }
+      logger.info("Adding updates to audit log");
+      const logStatement = updated
+        ? buildAuditLogTransactPut({
+            entry: {
+              module: Modules.ORG_INFO,
+              message: `Created GitHub team "${finalName}" for organization leads.`,
+              actor: metadata.initiator,
+              target: orgName,
+            },
+          })
+        : undefined;
+      const storeGithubIdOperation = async () => {
+        const commandTransaction = new TransactWriteItemsCommand({
+          TransactItems: [
+            ...(logStatement ? [logStatement] : []),
+            {
+              Update: {
+                TableName: genericConfig.SigInfoTableName,
+                Key: marshall({
+                  primaryKey: `DEFINE#${orgName}`,
+                  entryId: "0",
+                }),
+                UpdateExpression:
+                  "SET leadsGithubTeamId = :githubTeamId, updatedAt = :updatedAt",
+                ExpressionAttributeValues: marshall({
+                  ":githubTeamId": teamId,
+                  ":updatedAt": new Date().toISOString(),
+                }),
+              },
+            },
+          ],
+        });
+        return await dynamo.send(commandTransaction);
+      };
+
+      await retryDynamoTransactionWithBackoff(
+        storeGithubIdOperation,
+        logger,
+        `Store GitHub team ID for ${orgName}`,
+      );
+    });
+  } finally {
+    try {
+      await redisClient.quit();
+    } catch {
+      redisClient.disconnect();
+    }
+  }
+};

src/api/sqs/handlers/index.ts

@@ -3,3 +3,4 @@ export { emailMembershipPassHandler } from "./emailMembershipPassHandler.js";
 export { provisionNewMemberHandler } from "./provisionNewMember.js";
 export { sendSaleEmailHandler } from "./sendSaleEmailHandler.js";
 export { emailNotificationsHandler } from "./emailNotifications.js";
+export { createOrgGithubTeamHandler } from "./createOrgGithubTeam.js";

src/api/sqs/index.ts

@@ -22,6 +22,7 @@ import {
 import { ValidationError } from "../../common/errors/index.js";
 import { RunEnvironment } from "../../common/roles.js";
 import { environmentConfig } from "../../common/config.js";
+import { createOrgGithubTeamHandler } from "./handlers/createOrgGithubTeam.js";
 
 export type SQSFunctionPayloadTypes = {
   [K in keyof typeof sqsPayloadSchemas]: SQSHandlerFunction<K>;
@@ -39,6 +40,7 @@ const handlers: SQSFunctionPayloadTypes = {
   [AvailableSQSFunctions.ProvisionNewMember]: provisionNewMemberHandler,
   [AvailableSQSFunctions.SendSaleEmail]: sendSaleEmailHandler,
   [AvailableSQSFunctions.EmailNotifications]: emailNotificationsHandler,
+  [AvailableSQSFunctions.CreateOrgGithubTeam]: createOrgGithubTeamHandler,
 };
 export const runEnvironment = process.env.RunEnvironment as RunEnvironment;
 export const currentEnvironmentConfig = environmentConfig[runEnvironment];