methods/github/server

The github sign-in method, exported at @convex-dev/auth/methods/github/server.

Type Aliases

GithubOptions

type GithubOptions = object;

App-defined config for setting up the github method.

Properties

Property	Type	Description
allowedRedirectOrigins	string[]	Origins redirectTo may point at, e.g. ["https://app.example.com"] for open-redirect prevention.
component	ComponentApi	The GitHub oauth component instance, i.e. components.authGithub.

---

GithubProfile

type GithubProfile = Infer<typeof vGithubProfile>;

---

GithubUserInfo

type GithubUserInfo = object;

The responses the component's userinfo endpoints produce, keyed the way USER_INFO_ENDPOINTS names them. This is what GitHub is trusted to return; the responses are not validated against it at runtime.

Properties

Property	Type
emails	GithubEmail[]
user	GithubUser

Variables

vGithubProfile

const vGithubProfile: VObject<{
  avatarUrl?: string;
  email?: string;
  emailVerified: boolean;
  id: string;
  login: string;
  name?: string;
}, {
  avatarUrl: VString<string | undefined, "optional">;
  email: VString<string | undefined, "optional">;
  emailVerified: VBoolean<boolean, "required">;
  id: VString<string, "required">;
  login: VString<string, "required">;
  name: VString<string | undefined, "optional">;
}, "required", "id" | "email" | "name" | "emailVerified" | "login" | "avatarUrl">;

The account profile that the github method produces. GitHub is plain OAuth (no id_token), so identity comes from its userinfo endpoints. This is the exact shape the mapping emits, so the app can validate against it precisely.

Functions

normalizeGithubProfile()

function normalizeGithubProfile(userInfoResponses): object;

Map GitHub's userinfo responses to GithubProfile.

Parameters

Parameter	Type
userInfoResponses	GithubUserInfo | undefined

Returns

object

avatarUrl?

optional avatarUrl?: string;

email?

optional email?: string;

emailVerified

emailVerified: boolean;

id

id: string;

login

login: string;

name?

optional name?: string;

---

setupGithub()

function setupGithub<UsersTable>(core, options): object;

Built-in sign-in method for GitHub. Wire it up with the GitHub oauth component:

const auth = setupConvexAuth({ component: components.auth });
export const { signOut, refreshSession, isAuthenticated } = auth;

export const { startSignInWithGithub, completeSignInWithGithub } = setupGithub(auth, {
  component: components.authGithub,
  allowedRedirectOrigins: ["https://app.example.com", "http://localhost:5173"],
}).attachUserCallbacks({ createUser: internal.users.createUserGithub });

Setup:

1. Install the component in convex.config.ts under httpPrefix: "/oauth/github", binding GitHub's CLIENT_ID and CLIENT_SECRET.
2. Register <site-url>/oauth/github/callback as the redirect URI with GitHub.

The httpPrefix alone determines the callback URL.

Type Parameters

Type Parameter
UsersTable extends string

Parameters

Parameter	Type
core	AuthCore<UsersTable>
options	GithubOptions

Returns

attachUserCallbacks()

attachUserCallbacks(callbacks): object;

Supply the app's user callbacks (see UserCallbacks for how their args must be declared) and get the functions of this method to export.

Parameters

Parameter	Type
callbacks	UserCallbacks<"github", { avatarUrl?: string; email?: string; emailVerified: boolean; id: string; login: string; name?: string; }, UsersTable>

Returns

object

completeSignInWithGithub

completeSignInWithGithub: RegisteredMutation<"public", {
  code: string;
  state: string;
}, Promise<
  | {
  status: "complete";
  tokens: {
     accessToken: string;
     refreshToken: string;
     refreshTokenExpiresAt: number;
     userId: string;
  };
}
  | {
  status: "error";
  userError: {
     error: "INVALID_CODE";
  };
}>> = completeSignIn;

startSignInWithGithub

startSignInWithGithub: RegisteredMutation<"public", {
  redirectTo: string;
}, Promise<{
  redirect: string;
  state: string;
}>> = startSignIn;