Skip to Content

GitLab

The GitLab enables tools and to call the GitLab REST API  on behalf of a , 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 below).

What’s documented here

This page describes how to use and configure GitLab auth with Arcade:

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- see your brand on the consent screen and you control rate limits and scopes.


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:

OwnerWhere to create itBest for
A userEdit profile → Applications (https://gitlab.com/-/user_settings/applications)Personal use, prototypes
A groupGroup → Settings → ApplicationsTeam/organization integrations
The whole instanceAdmin Area → Applications (self-managed only)Instance-wide, admin-managed

The steps below use a -owned application on GitLab.com; group and instance applications use the same fields.

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.

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 .)

Fill in the application details

  • Name: a descriptive name your 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 need (see 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

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).


Scopes

GitLab OAuth scopes are space-delimited. The commonly useful ones for tools and :

ScopeGrants
read_userRead the authenticated user’s profile (/api/v4/user)
openid, profile, emailOpenID Connect identity claims
read_apiRead-only access to the full API (projects, issues, MRs, …)
apiFull read/write API access
read_repositoryRead repository files over the API
write_repositoryWrite repository files over the API

Request the least privilege your need. read_user is a good default for verifying identity; add read_api / api only when a tool reads or writes data. The exact scope strings must match what your GitLab application was registered with.


Configure GitLab auth in Arcade

When using your own app credentials, configure your to use a custom user verifier. Without this, your end-users will not be able to use your app or in production.

Configure GitLab auth using the Arcade Dashboard

Access the Arcade Dashboard

Go to 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).

  • 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.

When you use tools that require GitLab auth with your Arcade , Arcade automatically uses this provider. For multiple GitLab providers, see using multiple auth providers of the same type.


Using GitLab auth in app code

Use the GitLab in your own and AI apps to get a token for the GitLab API. See authorizing agents with Arcade for how this works.

Python
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"])

Using GitLab auth in custom tools

You can author your own custom tools that call the GitLab API.

Use the GitLab() auth class to mark a as requiring GitLab authorization. The context.authorization.token field is automatically populated with the ’s GitLab token:

Python
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.

Create the application on your instance

Create an OAuth application on your instance (, 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):

SettingValue
Authorization endpointhttps://{your-gitlab-host}/oauth/authorize
Token endpointhttps://{your-gitlab-host}/oauth/token
Refresh endpointhttps://{your-gitlab-host}/oauth/token (same as token)
Scope delimitera space
PKCEenabled (S256)

Enter the Client ID / Client Secret from your instance application and copy the generated Redirect URL back into that application.

Then pass your custom provider ID when starting auth:

Python
client = Arcade() auth_response = client.auth.start( user_id=user_id, provider="my-gitlab-instance", # your custom provider ID scopes=["read_user"], )

Troubleshooting

SymptomLikely causeFix
redirect_uri mismatch on the consent screenThe app’s Redirect URI doesn’t match Arcade’s generated URLCopy the exact Redirect URL from the Arcade provider into the GitLab application
invalid_scopeA requested scope isn’t enabled on the applicationAdd the scope to the GitLab application, or request only enabled scopes
401 Unauthorized from the APIToken expired or wrong scopeRe-authorize; ensure the tool requests a scope that covers the endpoint
Consent screen shows the wrong app nameUsing the default Arcade providerRegister your own application and configure it as above

Additional resources

Last updated on