Better Auth · Const

gitlab

Better Auth's GitLab provider enables OAuth sign-in through GitLab.com or a self-hosted GitLab instance. Configure credentials under socialProviders.gitlab, then invoke signIn.social with provider: "gitlab".

How it works

GitLab is configured as a social provider with application credentials and optionally an issuer URL. The client starts authentication through signIn.social using provider: "gitlab"; self-hosted GitLab deployments can provide their own issuer.

Syntax

socialProviders: { gitlab: { clientId, clientSecret, issuer? } }
await authClient.signIn.social({ provider: "gitlab" })

Parameters

Name	Type	Description
`clientId`	`string`	GitLab application Client ID.
`clientSecret`	`string`	GitLab application Client Secret.
`issuer`	`string`	Optional GitLab instance URL; defaults to GitLab.com.
`provider`	`string`	Social provider identifier; set to `gitlab` for GitLab sign-in.

Returns

The page does not specify a return value for the GitLab provider configuration or sign-in call.

Key points

Create a GitLab OAuth application and provide both its client ID and client secret.
Register GitLab in the server-side auth instance under socialProviders.
Use issuer to target a self-hosted GitLab server.
GitLab.com needs no explicit issuer because it is the default endpoint.
Start the browser-based authentication flow through the client signIn.social method.
Pass gitlab as the social provider identifier when initiating sign-in.

Common mistakes

Register the callback URL expected by Better Auth for local development; production should use your application URL.
Changing the auth route base path requires updating GitLab's registered redirect URL.

Example: Configure and sign in with GitLab

import { betterAuth } from "better-auth";
import { createAuthClient } from "better-auth/client";

export const auth = betterAuth({
  socialProviders: {
    gitlab: {
      clientId: process.env.GITLAB_CLIENT_ID!,
      clientSecret: process.env.GITLAB_CLIENT_SECRET!,
      issuer: "https://gitlab.com",
    },
  },
});

const authClient = createAuthClient();
await authClient.signIn.social({ provider: "gitlab" });

Configure GitLab in the server auth instance, then start the OAuth flow with the GitLab provider identifier.

When to use it

GitLab.com sign-in

Users authenticate with GitLab.com accounts in a standard OAuth deployment.

Self-hosted GitLab authentication

An organization runs GitLab on its own domain and needs that instance used for authentication.

Multi-provider social login

An application offers GitLab as one option among several social login providers.

Interview questions

QHow do you configure GitLab sign-in in Better Auth?

Add a gitlab entry under socialProviders with the GitLab client ID and client secret. Then call authClient.signIn.social({ provider: "gitlab" }) to begin sign-in.

Follow-up: How would you support a self-hosted GitLab instance? Set the provider's issuer to that GitLab instance URL instead of relying on the GitLab.com default.

QWhich provider identifier starts the GitLab OAuth flow?

The provider identifier passed to signIn.social is gitlab. The same identifier is used as the key in the socialProviders configuration.

Follow-up: What must change if the application's auth route prefix changes? Update the GitLab OAuth redirect URL to match the new callback path.

QWhen should the GitLab issuer option be set?

issuer is optional because GitLab.com is the default. For a self-hosted deployment, configure it with the deployment's URL, such as https://gitlab.company.com.

Follow-up: When can issuer be omitted? Omit it when authenticating against GitLab.com; specify it for a non-default GitLab instance.

socialProviders
signIn.social
clientId
clientSecret
issuer

Source: GitLab. Checked 2026-10-15.