Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

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.ts
index 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",
+ });
+ });
+
+ 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.ts
index 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">, org
type 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.mdx
index 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>