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:
- Creating your own GitLab OAuth application
- Configuring the provider in Arcade
- Using GitLab auth in your app code or custom tools
- Self-managed GitLab instances
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:
| 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 -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_useris 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 :
| 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 |
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.
Dashboard GUI
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).
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.
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:
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):
| 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.
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
| 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 |