Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
fix(github-org-sync): match GitHub logins by rule strength, and skip ambiguous ones
Scott Wilson6afc4fca0e59
diff --git a/backend/src/ee/services/github-org-sync/github-org-sync-service.test.ts b/backend/src/ee/services/github-org-sync/github-org-sync-service.test.tsindex d3457c417a..a66666325a 100644--- a/backend/src/ee/services/github-org-sync/github-org-sync-service.test.ts+++ b/backend/src/ee/services/github-org-sync/github-org-sync-service.test.ts@@ -96,42 +96,98 @@ describe("buildGithubMemberMatcher", () => {user: email === null ? null : { email },inviteEmail});+ const matched = (result: ReturnType<ReturnType<typeof buildGithubMemberMatcher>>) =>+ result.status === "matched" ? { id: (result.member as { id: string }).id, rule: result.rule } : result;- test("matches a login equal to the email prefix", () => {- const match = buildGithubMemberMatcher([member("a", "[email protected]")]);- expect(match("Jane.Doe")?.id).toBe("a");- expect(match("someone-else")).toBeUndefined();- });+ describe("email rule", () => {+ test("matches a login equal to the email prefix", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(matched(match("Jane.Doe"))).toEqual({ id: "a", rule: "email" });+ });- test("matches a login that appends the domain name to the email prefix", () => {- const match = buildGithubMemberMatcher([member("a", "[email protected]")]);- expect(match("janeacme")?.id).toBe("a");- expect(match("acme")).toBeUndefined();+ test("matches across separator differences between email and login", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(matched(match("janedoe"))).toEqual({ id: "a", rule: "email" });+ expect(matched(match("jane-doe"))).toEqual({ id: "a", rule: "email" });+ });});- test("matches when the longest email part is contained in the login", () => {- const match = buildGithubMemberMatcher([member("a", "[email protected]")]);- expect(match("smithson-dev")?.id).toBe("a");+ describe("org suffix rule", () => {+ test("matches a login that appends the organization name to the email prefix", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(matched(match("janeacme"))).toEqual({ id: "a", rule: "email-with-org-suffix" });+ });++ test("does not match the organization name alone", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(match("acme").status).toBe("unmatched");+ });});- test("does not match on an email part shorter than four characters", () => {- const match = buildGithubMemberMatcher([member("a", "[email protected]")]);- expect(match("xxliyy")).toBeUndefined();+ describe("name part rule", () => {+ test("matches when a login component equals the longest email part", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(matched(match("smithson-dev"))).toEqual({ id: "a", rule: "name-part" });+ });++ test("does not match a name part buried inside a login component", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]"), member("b", "[email protected]")]);+ expect(match("0xarshdeep").status).toBe("unmatched");+ expect(match("carlosmonastyrski").status).toBe("unmatched");+ });++ test("does not match a name part shorter than four characters", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]")]);+ expect(match("li-jones").status).toBe("unmatched");+ });});- test("returns the first matching member, preserving input order", () => {- const match = buildGithubMemberMatcher([member("first", "[email protected]"), member("second", "[email protected]")]);- expect(match("bob")?.id).toBe("first");+ describe("rule precedence", () => {+ test("an exact email match beats a name part match found earlier in the list", () => {+ const match = buildGithubMemberMatcher([+ member("weak", "[email protected]"),+ member("exact", "[email protected]")+ ]);+ expect(matched(match("scott-ray-wilson"))).toEqual({ id: "exact", rule: "email" });+ });++ test("falls through to the next rule only when no member matches the stronger one", () => {+ const match = buildGithubMemberMatcher([member("weak", "[email protected]")]);+ expect(matched(match("scott-ray-wilson"))).toEqual({ id: "weak", rule: "name-part" });+ });});- test("falls back to inviteEmail and skips members with neither", () => {- const match = buildGithubMemberMatcher([member("no-email", null), member("invited", null, "[email protected]")]);- expect(match("bob")?.id).toBe("invited");+ describe("ambiguity", () => {+ test("reports rather than guesses when two members match the same rule", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]"), member("b", "[email protected]")]);+ const result = match("janedoe");+ expect(result).toEqual({+ status: "ambiguous",+ rule: "email",+ emails: ["[email protected]", "[email protected]"]+ });+ });++ test("does not report ambiguity for a member listed twice with the same email", () => {+ const match = buildGithubMemberMatcher([member("a", "[email protected]"), member("b", "[email protected]")]);+ expect(match("jane").status).toBe("matched");+ });});- test("ignores a malformed email instead of throwing", () => {- const match = buildGithubMemberMatcher([member("bad", "not-an-email"), member("good", "[email protected]")]);- expect(() => match("bob")).not.toThrow();- expect(match("bob")?.id).toBe("good");+ describe("input handling", () => {+ test("falls back to inviteEmail and skips members with neither", () => {+ const match = buildGithubMemberMatcher([member("no-email", null), member("invited", null, "[email protected]")]);+ expect(matched(match("bob"))).toEqual({ id: "invited", rule: "email" });+ });++ test("ignores a malformed email instead of throwing", () => {+ const match = buildGithubMemberMatcher([member("bad", "not-an-email"), member("good", "[email protected]")]);+ expect(() => match("bob")).not.toThrow();+ expect(matched(match("bob"))).toEqual({ id: "good", rule: "email" });+ });++ test("returns unmatched for an empty member list", () => {+ expect(buildGithubMemberMatcher([])("anyone").status).toBe("unmatched");+ });});});diff --git a/backend/src/ee/services/github-org-sync/github-org-sync-service.ts b/backend/src/ee/services/github-org-sync/github-org-sync-service.tsindex 4a448ce42a..b2c3192072 100644--- a/backend/src/ee/services/github-org-sync/github-org-sync-service.ts+++ b/backend/src/ee/services/github-org-sync/github-org-sync-service.ts@@ -206,36 +206,80 @@ export const fetchGithubOrgTeams = async (octokit: Pick<Octokit, "graphql">, orgtype TMatchableMember<T> = { user?: { email?: string | null } | null; inviteEmail?: string | null } & T;-// ~16M (login, member) comparisons on a 640-team org, so per-member fields are derived once per-// sync. Order must stay input order, or `find` picks a different member than before.+// Weakest rule a login is allowed to match on. A name part shorter than this collides constantly.+const GITHUB_MIN_NAME_PART_LENGTH = 4;++const AMBIGUOUS_LOGIN_REPORT_LIMIT = 20;++export const GithubMemberMatchRule = {+ Email: "email",+ EmailWithOrgSuffix: "email-with-org-suffix",+ NamePart: "name-part"+} as const;++export type TGithubMemberMatchRule = (typeof GithubMemberMatchRule)[keyof typeof GithubMemberMatchRule];++export type TGithubMemberMatch<T> =+ | { status: "matched"; member: T; rule: TGithubMemberMatchRule }+ | { status: "ambiguous"; rule: TGithubMemberMatchRule; emails: string[] }+ | { status: "unmatched" };++const SEPARATORS = new RE2(/[._-]/g);+const stripSeparators = (value: string) => value.replace(SEPARATORS, "");++/**+ * Resolves a GitHub login to the org member it belongs to.+ *+ * Rules are tried strongest first across every member, so an exact email match always beats a name+ * fragment no matter what order members arrive in. A login that two members match equally well is+ * reported as ambiguous rather than resolved, because guessing hands one of them the other's+ * project access.+ */export const buildGithubMemberMatcher = <T>(members: TMatchableMember<T>[]) => {- const emailSplitRegex = new RE2(/[._-]/);+ // ~16M (login, member) comparisons on a 640-team org, so per-member fields are derived once per+ // sync rather than once per comparison.const candidates = members.flatMap((member) => {const email = member.user?.email || member.inviteEmail;if (!email) return [];const [rawPrefix, rawDomain] = email.split("@");if (!rawPrefix || !rawDomain) return [];const emailPrefix = rawPrefix.toLowerCase();+ const parts = emailPrefix.split(new RE2(/[._-]/));return [{member,- emailPrefix,- domainName: rawDomain.toLowerCase().split(".")[0],- longestEmailPart: emailPrefix.split(emailSplitRegex).reduce((a, b) => (a.length > b.length ? a : b), "")+ email: email.toLowerCase(),+ compactPrefix: stripSeparators(emailPrefix),+ orgSuffixed: stripSeparators(emailPrefix) + stripSeparators(rawDomain.toLowerCase().split(".")[0]),+ longestPart: parts.reduce((a, b) => (a.length > b.length ? a : b), "")}];});- return (githubLogin: string) => {- const githubUsername = githubLogin.toLowerCase();- return candidates.find(- ({ emailPrefix, domainName, longestEmailPart }) =>- emailPrefix === githubUsername ||- (githubUsername.endsWith(domainName) &&- githubUsername.length > domainName.length &&- emailPrefix === githubUsername.slice(0, -domainName.length)) ||- (longestEmailPart.length >= 4 && githubUsername.includes(longestEmailPart))- )?.member;+ return (githubLogin: string): TGithubMemberMatch<T> => {+ const login = githubLogin.toLowerCase();+ const compactLogin = stripSeparators(login);+ const loginParts = new Set(login.split(new RE2(/[._-]/)));++ const rules: [TGithubMemberMatchRule, (c: (typeof candidates)[number]) => boolean][] = [+ [GithubMemberMatchRule.Email, (c) => c.compactPrefix === compactLogin],+ [GithubMemberMatchRule.EmailWithOrgSuffix, (c) => c.orgSuffixed === compactLogin],+ [+ GithubMemberMatchRule.NamePart,+ (c) => c.longestPart.length >= GITHUB_MIN_NAME_PART_LENGTH && loginParts.has(c.longestPart)+ ]+ ];++ for (const [rule, predicate] of rules) {+ const hits = candidates.filter(predicate);+ const distinct = [...new Map(hits.map((hit) => [hit.email, hit])).values()];+ if (distinct.length === 1) return { status: "matched", member: distinct[0].member, rule };+ if (distinct.length > 1) {+ return { status: "ambiguous", rule, emails: distinct.map((hit) => hit.email).sort() };+ }+ }++ return { status: "unmatched" };};};@@ -796,6 +840,7 @@ export const githubOrgSyncServiceFactory = ({const startTime = Date.now();const syncErrors: string[] = [];+ const ambiguousLogins = new Map<string, string[]>();const octokit = new Octokit({ auth: orgAccessToken });@@ -907,13 +952,15 @@ export const githubOrgSyncServiceFactory = ({(githubTeamMembersByName.get(teamName) ?? []).forEach((login) => {const githubUsername = login.toLowerCase();- const matchingMember = matchGithubLogin(githubUsername);+ const result = matchGithubLogin(githubUsername);- if (matchingMember?.user?.id) {- expectedUserIds.add(matchingMember.user.id);+ if (result.status === "matched" && result.member.user?.id) {+ expectedUserIds.add(result.member.user.id);logger.info(- `Matched GitHub user ${githubUsername} to email ${matchingMember.user?.email || matchingMember.inviteEmail}`+ `Matched GitHub user ${githubUsername} to email ${result.member.user?.email || result.member.inviteEmail} by ${result.rule}`);+ } else if (result.status === "ambiguous") {+ ambiguousLogins.set(githubUsername, result.emails);}});@@ -969,6 +1016,26 @@ export const githubOrgSyncServiceFactory = ({usageMeteringService.emit(orgPermission.orgId, PamIdentities.key);}+ if (ambiguousLogins.size) {+ logger.warn(+ { orgId: orgPermission.orgId, count: ambiguousLogins.size },+ "GitHub org sync skipped logins that more than one organization member matched"+ );+ // Capped so a badly aliased org cannot return a response the client has to scroll through.+ const listed = [...ambiguousLogins.entries()].slice(0, AMBIGUOUS_LOGIN_REPORT_LIMIT);+ syncErrors.push(+ ...listed.map(+ ([login, emails]) =>+ `GitHub user '${login}' matches more than one organization member (${emails.join(", ")}), so their team memberships were not synced. Align the member's email with their GitHub username.`+ )+ );+ if (ambiguousLogins.size > listed.length) {+ syncErrors.push(+ `${ambiguousLogins.size - listed.length} further GitHub users were skipped for the same reason.`+ );+ }+ }+const syncDuration = Date.now() - startTime;logger.info(diff --git a/docs/documentation/platform/github-org-sync.mdx b/docs/documentation/platform/github-org-sync.mdxindex 9ea6348926..061cf6544a 100644--- a/docs/documentation/platform/github-org-sync.mdx+++ b/docs/documentation/platform/github-org-sync.mdx@@ -103,6 +103,26 @@ You can manually synchronize GitHub teams for all organization members who have</Step></Steps>+## How members are matched++Manual sync compares each GitHub username against the email address of every member in your+organization. It tries three rules in order and stops at the first rule that identifies exactly one+member:++1. The part of the email address before the `@` equals the username, ignoring dots, hyphens and+ underscores. `[email protected]` matches `janedoe`.+2. The username is that same email prefix followed by your organization's name. `[email protected]`+ matches `janeacme`.+3. The longest part of the email prefix is one whole part of the username. `[email protected]`+ matches `smithson-dev`.++When two members match the same rule, the sync skips that GitHub user and lists them in the+**Sync Now** result instead of choosing between them. Give one of the members an email address whose+prefix matches their GitHub username to resolve it.++A GitHub user who matches no member isn't added to any group. That's expected for accounts with no+Infisical member, such as bots and outside collaborators.+## Troubleshooting<AccordionGroup>