ArcadeAI · EricGustin · Jun 14, 2026 · Jun 14, 2026
diff --git a/app/en/references/auth-providers/gitlab/page.mdx b/app/en/references/auth-providers/gitlab/page.mdx
@@ -0,0 +1,326 @@
+import { Tabs, Callout, Steps } from "nextra/components";
+
+# GitLab
+
+The GitLab auth provider enables tools and agents to call the [GitLab REST API](https://docs.gitlab.com/ee/api/rest/) on behalf of a user, using GitLab's OAuth 2.0 flow.
+
+It works with **GitLab.com** out of the box, and with **self-managed GitLab** instances via a custom provider (see [Self-managed GitLab](#self-managed-gitlab-and-gitlab-dedicated) below).
+
+## What's documented here
+
+This page describes how to use and configure GitLab auth with Arcade:
+
+- [Creating your own GitLab OAuth application](#create-a-gitlab-oauth-application)
+- [Configuring the provider in Arcade](#configure-gitlab-auth-in-arcade)
+- Using GitLab auth in your [app code](#using-gitlab-auth-in-app-code) or [custom tools](#using-gitlab-auth-in-custom-tools)
+- [Self-managed GitLab](#self-managed-gitlab-and-gitlab-dedicated) instances
+
+<Callout>
+  To try GitLab auth immediately, Arcade provides a **default GitLab provider** —
+  no configuration required. For production you should register your **own** GitLab
+  application so end-users see your brand on the consent screen and you control
+  rate limits and scopes.
+</Callout>
+
+---
+
+## Create a GitLab OAuth application
+
+You can register an OAuth application at three levels in GitLab. Pick the one that matches who should own the integration:
+
+| Owner | Where to create it | Best for |
+| ----- | ------------------ | -------- |
+| **A user** | **Edit profile → Applications** (`https://gitlab.com/-/user_settings/applications`) | Personal use, prototypes |
+| **A group** | **Group → Settings → Applications** | Team/organization integrations |
+| **The whole instance** | **Admin Area → Applications** (self-managed only) | Instance-wide, admin-managed |
+
+The steps below use a user-owned application on GitLab.com; group and instance applications use the same fields.
+
+<Callout type="info">
+  You need the **Arcade-generated redirect URL** to fill in the application's
+  "Redirect URI". If you create the Arcade provider first you can copy it from the
+  dashboard; otherwise leave a placeholder and update it after
+  [configuring the provider in Arcade](#configure-gitlab-auth-in-arcade).
+</Callout>
+
+<Steps>
+
+### Open the Applications page
+
+Sign in to GitLab, click your avatar (top-right) → **Edit profile**, then **Applications** in the left sidebar. (Direct link: [gitlab.com/-/user_settings/applications](https://gitlab.com/-/user_settings/applications).)
+
+### Fill in the application details
+
+- **Name**: a descriptive name your users will see on the consent screen (e.g. "Acme AI Assistant").
+- **Redirect URI**: the redirect URL generated by Arcade for this provider (one per line if you have several).
+- **Confidential**: leave **checked** ✅. Arcade is a confidential client and authenticates with a client secret.
+- **Scopes**: select the scopes your tools need (see [Scopes](#scopes) below). For read-only identity, `read_user` is enough.
+
+### Save and copy the credentials
+
+Click **Save application**. GitLab shows the new application with its:
+
+- **Application ID** → this is your **Client ID**
+- **Secret** → this is your **Client Secret**
+
+<Callout type="warning">
+  On GitLab.com the **Secret is shown only once**. Copy it immediately and store
+  it securely — if you lose it you must rotate it (which invalidates the old one).
+</Callout>
+
+</Steps>
+
+---
+
+## Scopes
+
+GitLab OAuth scopes are space-delimited. The commonly useful ones for tools and agents:
+
+| Scope | Grants |
+| ----- | ------ |
+| `read_user` | Read the authenticated user's profile (`/api/v4/user`) |
+| `openid`, `profile`, `email` | OpenID Connect identity claims |
+| `read_api` | Read-only access to the full API (projects, issues, MRs, …) |
+| `api` | Full read/write API access |
+| `read_repository` | Read repository files over the API |
+| `write_repository` | Write repository files over the API |
+
+<Callout type="info">
+  Request the **least privilege** your tools need. `read_user` is a good default
+  for verifying identity; add `read_api` / `api` only when a tool reads or writes
+  project data. The exact scope strings must match what your GitLab application was
+  registered with.
+</Callout>
+
+---
+
+## Configure GitLab auth in Arcade
+
+<Callout type="info">
+  When using your own app credentials, configure your project to use a
+  [custom user verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
+  Without this, your end-users will not be able to use your app or agent in
+  production.
+</Callout>
+
+<Tabs items={["Dashboard GUI"]}>
+<Tabs.Tab>
+
+### Configure GitLab auth using the Arcade Dashboard
+
+<Steps>
+
+#### Access the Arcade Dashboard
+
+Go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, the dashboard is at `http://localhost:9099/dashboard` by default (adjust host/port to your environment).
+
+#### Navigate to the OAuth Providers page
+
+- Under the **Connections** section of the left-side menu, click **Connected Apps**.
+- Click **Add OAuth Provider** (top-right).
+- Select the **Included Providers** tab.
+- In the **Provider** dropdown, select **GitLab**.
+
+#### Enter the provider details
+
+- Choose a unique **ID** for your provider (e.g. `my-gitlab-provider`).
+- Optionally enter a **Description**.
+- Enter the **Client ID** (Application ID) and **Client Secret** from your GitLab application.
+- Note the **Redirect URL** generated by Arcade — add it to your GitLab application's **Redirect URI** if you have not already.
+
+#### Create the provider
+
+Click **Create**. The provider is ready to use.
+
+</Steps>
+
+When you use tools that require GitLab auth with your Arcade account, Arcade automatically uses this provider. For multiple GitLab providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type).
+
+</Tabs.Tab>
+</Tabs>
+
+---
+
+## Using GitLab auth in app code
+
+Use the GitLab auth provider in your own agents and AI apps to get a user token for the GitLab API. See [authorizing agents with Arcade](/get-started/about-arcade) for how this works.
+
+<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
+<Tabs.Tab>
+
+```python {8-12}
+import requests
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+user_id = "{arcade_user_id}"
+
+# Start the authorization process
+auth_response = client.auth.start(
+    user_id=user_id,
+    provider="gitlab",
+    scopes=["read_user"],
+)
+
+if auth_response.status != "completed":
+    print("Please complete the authorization challenge in your browser:")
+    print(auth_response.url)
+
+# Wait for the authorization to complete
+auth_response = client.auth.wait_for_completion(auth_response)
+
+token = auth_response.context.token
+
+# Call the GitLab API as the user
+response = requests.get(
+    "https://gitlab.com/api/v4/user",
+    headers={"Authorization": f"Bearer {token}"},
+)
+response.raise_for_status()
+print(response.json()["username"])
+```
+
+</Tabs.Tab>
+<Tabs.Tab>
+
+```javascript {8-10}
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade();
+
+const userId = "{arcade_user_id}";
+
+// Start the authorization process
+let authResponse = await client.auth.start(userId, "gitlab", {
+  scopes: ["read_user"],
+});
+
+if (authResponse.status !== "completed") {
+  console.log("Please complete the authorization challenge in your browser:");
+  console.log(authResponse.url);
+}
+
+// Wait for the authorization to complete
+authResponse = await client.auth.waitForCompletion(authResponse);
+
+const token = authResponse.context.token;
+
+// Call the GitLab API as the user
+const response = await fetch("https://gitlab.com/api/v4/user", {
+  headers: { Authorization: `Bearer ${token}` },
+});
+const user = await response.json();
+console.log(user.username);
+```
+
+</Tabs.Tab>
+</Tabs>
+
+---
+
+## Using GitLab auth in custom tools
+
+You can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that call the GitLab API.
+
+Use the `GitLab()` auth class to mark a tool as requiring GitLab authorization. The `context.authorization.token` field is automatically populated with the user's GitLab token:
+
+```python {5-6,9-13}
+from typing import Annotated
+
+import httpx
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import GitLab
+
+
+@tool(requires_auth=GitLab(scopes=["read_user"]))
+async def whoami(
+    context: ToolContext,
+) -> Annotated[str, "The authenticated GitLab user's username"]:
+    """Return the authenticated GitLab user's username."""
+    if not context.authorization or not context.authorization.token:
+        raise ValueError("No token found in context")
+
+    headers = {"Authorization": f"Bearer {context.authorization.token}"}
+    async with httpx.AsyncClient() as client:
+        response = await client.get("https://gitlab.com/api/v4/user", headers=headers)
+        response.raise_for_status()
+        return response.json()["username"]
+```
+
+---
+
+## Self-managed GitLab and GitLab Dedicated
+
+The included GitLab provider targets **gitlab.com**. For a self-managed instance or GitLab Dedicated, create a **Custom Provider** in Arcade with your instance's URLs.
+
+<Steps>
+
+#### Create the application on your instance
+
+Create an OAuth application on your instance (User, Group, or **Admin Area → Applications**), exactly as for GitLab.com. Use your instance hostname instead of `gitlab.com`.
+
+#### Add a Custom Provider in Arcade
+
+In the dashboard, **Add OAuth Provider → Custom Providers**, then set the endpoints, replacing `{your-gitlab-host}` with your instance hostname (e.g. `gitlab.example.com`):
+
+| Setting | Value |
+| ------- | ----- |
+| **Authorization endpoint** | `https://{your-gitlab-host}/oauth/authorize` |
+| **Token endpoint** | `https://{your-gitlab-host}/oauth/token` |
+| **Refresh endpoint** | `https://{your-gitlab-host}/oauth/token` (same as token) |
+| **Scope delimiter** | a space |
+| **PKCE** | enabled (`S256`) |
+
+Enter the **Client ID** / **Client Secret** from your instance application and copy the generated **Redirect URL** back into that application.
+
+</Steps>
+
+Then pass your custom provider ID when starting auth:
+
+<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
+<Tabs.Tab>
+
+```python {4}
+client = Arcade()
+
+auth_response = client.auth.start(
+    user_id=user_id,
+    provider="my-gitlab-instance",  # your custom provider ID
+    scopes=["read_user"],
+)
+```
+
+</Tabs.Tab>
+<Tabs.Tab>
+
+```javascript {3}
+const client = new Arcade();
+
+let authResponse = await client.auth.start(userId, "my-gitlab-instance", {
+  scopes: ["read_user"],
+});
+```
+
+</Tabs.Tab>
+</Tabs>
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| ------- | ------------ | --- |
+| `redirect_uri` mismatch on the consent screen | The app's Redirect URI doesn't match Arcade's generated URL | Copy the exact Redirect URL from the Arcade provider into the GitLab application |
+| `invalid_scope` | A requested scope isn't enabled on the application | Add the scope to the GitLab application, or request only enabled scopes |
+| `401 Unauthorized` from the API | Token expired or wrong scope | Re-authorize; ensure the tool requests a scope that covers the endpoint |
+| Consent screen shows the wrong app name | Using the default Arcade provider | Register your own application and configure it as above |
+
+---
+
+## Additional resources
+
+- [GitLab OAuth 2.0 documentation](https://docs.gitlab.com/ee/api/oauth2.html)
+- [GitLab REST API](https://docs.gitlab.com/ee/api/rest/)
+- [GitLab OAuth scopes](https://docs.gitlab.com/ee/integration/oauth_provider.html#view-all-authorized-applications)
+- [Arcade authorization guide](/get-started/about-arcade)
diff --git a/app/en/references/auth-providers/page.mdx b/app/en/references/auth-providers/page.mdx
@@ -63,6 +63,13 @@ For more information on how to customize your auth provider, select an auth prov
     link="/references/auth-providers/github"
     category="Auth"
   />
+  <ToolCard
+    name="GitLab"
+    image="gitlab"
+    summary="Authorize tools and agents with GitLab, including private repositories and merge requests"
+    link="/references/auth-providers/gitlab"
+    category="Auth"
+  />
   <ToolCard
     name="Google"
     image="google"

diff --git a/public/llms.txt b/public/llms.txt
@@ -1,4 +1,4 @@
-<!-- git-sha: 027403fb15a72f497ccba09bcf6f03e5766dbf3a generation-date: 2026-04-23T01:29:18.671Z -->
+<!-- git-sha: d4f33074582d3a59aa22284e4cd958b227d05bb2 generation-date: 2026-06-14T00:12:34.617Z -->
 
 # Arcade
 
@@ -32,6 +32,7 @@ Arcade delivers three core capabilities: Deploy agents even your security team w
 - [Errors](https://docs.arcade.dev/en/references/mcp/python/errors): This documentation page provides an overview of the various exception types related to the MCP server in the Arcade MCP Python framework. It details the hierarchy of MCP-specific errors, including their base classes and specific use cases, as well as re-exported exceptions from the
 - [Figma](https://docs.arcade.dev/en/references/auth-providers/figma): This documentation page provides guidance on using the Figma authentication provider with Arcade, enabling users to call Figma APIs via OAuth 2.0. It outlines the necessary configurations, required scopes for different tools, and steps to create a Figma app for
 - [GitHub](https://docs.arcade.dev/en/references/auth-providers/github): This documentation page provides guidance on using and configuring the GitHub auth provider with Arcade, enabling users to call GitHub APIs securely on behalf of users. It emphasizes the necessity of using GitHub Apps over OAuth Apps for enhanced security, granular permissions, and
+- [GitLab](https://docs.arcade.dev/en/references/auth-providers/gitlab): Documentation page
 - [Google](https://docs.arcade.dev/en/references/auth-providers/google): This documentation page provides guidance on using and configuring Google authentication with Arcade, enabling users to access Google/Google Workspace APIs through their applications. It outlines the benefits of using Arcade's default Google OAuth provider for quick integration, as well as instructions for setting up
 - [Hubspot](https://docs.arcade.dev/en/references/auth-providers/hubspot): This documentation page provides guidance on using and configuring the Hubspot authentication provider within the Arcade platform, enabling users to call Hubspot APIs on behalf of their applications. It outlines the steps for utilizing Arcade's default Hubspot auth provider, as well as instructions
 - [Linear](https://docs.arcade.dev/en/references/auth-providers/linear): This documentation page provides guidance on configuring and using the Linear authentication provider with Arcade, enabling users to call Linear APIs on behalf of users in their applications. It outlines the steps to create a Linear app, set up OAuth2 credentials, and integrate Linear auth