Skip to main content

​
What You Can Do

With GitLab connected, Overcut agents can:
  • Access repositories to clone, read, and update code
  • Manage issues by creating, updating, and commenting on GitLab issues
  • Handle merge requests by reviewing, commenting on, and managing merge requests
  • Run code operations such as cloning repositories and creating branches
  • Use webhook triggers to start workflows from GitLab events
  • Configure repositories for workspace-specific automation

​
Prerequisites

Before you connect GitLab, make sure you have:
  • A GitLab account on GitLab.com or on your self-hosted GitLab instance
  • An active Overcut workspace
  • A dedicated GitLab service account with Maintainer or Owner access to the repositories or groups you want Overcut to use
If you plan to connect a self-hosted GitLab instance, also make sure you have:
  • Your GitLab instance URL such as https://gitlab.example.com, served over HTTPS with a valid (non self-signed) TLS certificate
  • The GitLab instance is reachable from Overcut over the public internet so Overcut can complete the OAuth token exchange and call the GitLab API. If the instance sits behind a firewall or VPN, allow Overcut Cloud’s egress IP range
  • If you plan to use GitLab event triggers, the GitLab instance can also send outbound webhooks to Overcut at https://app.overcut.ai
  • An OAuth Application ID created in that GitLab instance
  • An OAuth Application Secret created in that GitLab instance
  • Access to sign in to that GitLab instance as the service account during setup
Use a dedicated service account instead of a personal account. This keeps your bot identity consistent, avoids permission changes when teammates leave, and makes automated activity easier to recognize.

​
Choose GitLab.com or self-hosted GitLab

In Overcut, go to Integrations, select Add Provider, then select GitLab. The Connect to GitLab dialog asks which kind of instance you use.

GitLab.com

Leave Connect to a self-hosted GitLab instance turned off. You only need the service account and GitLab.com sign-in.

Self-hosted GitLab

Turn on Connect to a self-hosted GitLab instance. Enter the URL and OAuth application credentials for your instance before authorizing access.
The self-hosted option displays these fields:
  • Instance URL
  • OAuth Application ID
  • OAuth Application Secret
These values are specific to your GitLab instance and are not required for GitLab.com.

​
Connect GitLab.com

1

Prepare your GitLab service account

Create or choose a dedicated GitLab user for Overcut. Add the account to the projects or groups you want to connect with Maintainer permissions, then sign in to GitLab.com as that account.
2

Open the GitLab connection

In Integrations, select Add Provider, then select GitLab. Leave Connect to a self-hosted GitLab instance turned off and select I am ready to continue.
3

Approve access in the popup

GitLab.com opens in a browser popup. Review the request and approve access for Overcut.

​
Connect a self-hosted GitLab instance

1

Prepare your GitLab service account

Create or choose a dedicated GitLab user for Overcut, then add that account to the projects or groups you want to connect.Give the account Maintainer or Owner access to the repositories and groups you want Overcut to use so it can work with repositories, issues, merge requests, and GitLab-triggered workflows.
2

Register an instance-wide OAuth application in GitLab

Overcut connects to self-hosted GitLab using an instance-wide OAuth application that a GitLab administrator registers in your GitLab instance. This step gives Overcut the Application ID and Application Secret it needs, and keeps the integration owned by the organization rather than an individual user or group.
An instance administrator must perform this step. If you are not a GitLab administrator, coordinate with the team that manages your GitLab instance.
In your self-hosted GitLab instance, go to the Admin area → Applications and select New application. For full instructions and screenshots, see GitLab’s official documentation on configuring GitLab as an OAuth 2.0 authentication identity provider.Use these settings when creating the application:
  • Name: any recognizable label such as Overcut
  • Redirect URI (labeled Callback URL in GitLab’s admin UI): https://app.overcut.ai/gitlab-auth-app/callback
  • Trusted: leave disabled
  • Confidential: enabled
  • Scopes: select api
After you save the application, GitLab displays the Application ID and Secret. Copy both values. You will paste them into Overcut in the next step.
GitLab typically shows the Application Secret only once. Store it securely when you first see it; if you lose it, you will need to regenerate the secret in GitLab and update Overcut.
3

Enter the self-hosted connection details in Overcut

In Integrations, select Add Provider, then select GitLab. Turn on Connect to a self-hosted GitLab instance and enter:
  • Instance URL
  • OAuth Application ID
  • OAuth Application Secret
4

Authorize access in your GitLab instance

Select I am ready to continue. Your configured GitLab instance opens in a browser popup.Sign in as the dedicated service account if needed, review the request, and approve access to complete the connection.

​
Verify the connection

Overcut confirms the connection and lists it under Integrations (see Connect a provider for the popup and confirmation details). Then confirm it can access what you expect:
  • Open your repository list in Overcut and confirm the expected GitLab repositories appear
  • Start creating or editing a workflow and verify you can select the connected GitLab repositories or projects
  • If you use GitLab event triggers, create a simple test change such as opening an issue, commenting on an issue, updating a merge request, or running a pipeline and confirm the workflow can respond
If you manage more than one GitLab environment, confirm that the repositories shown in Overcut belong to the same instance URL you entered during setup.

​
Connect another GitLab account or instance

Select Add Provider and choose GitLab again. Leave Connect to a self-hosted GitLab instance turned off to authorize another GitLab.com account, or turn it on to connect another self-hosted instance. Each connection appears separately under Integrations.

​
Troubleshooting

If the connection does not work as expected, check the following:
  • Wrong instance URL: Confirm you entered the full URL for the correct GitLab instance
  • Wrong OAuth credentials: Make sure the Application ID and Application Secret come from the same self-hosted GitLab instance you are connecting
  • Callback URL mismatch: If GitLab shows an “invalid redirect URI” error during authorization, edit the OAuth application in GitLab and set the Callback URL to exactly https://app.overcut.ai/gitlab-auth-app/callback.
  • Missing api scope: The OAuth application must have the api scope selected. If it is missing, edit the application in GitLab, enable the scope, and try connecting again.
  • Signed in to the wrong account: Complete authorization using the dedicated GitLab service account, not a personal account with limited access
  • Missing repository or group access: Verify the service account has Maintainer or Owner access to the repositories or groups you want to use in Overcut
  • Unexpected redirect destination: For self-hosted connections, authorization should open your own GitLab domain rather than GitLab.com
  • Popup blocked or failed: Allow popups for Overcut in your browser settings, then retry the connection
If you still cannot complete setup, repeat the connection flow and re-enter the instance URL and OAuth application credentials carefully.

​
GitLab.com vs self-hosted GitLab

Use GitLab.com when your repositories are hosted on GitLab.com. Use the self-hosted option when your team uses GitLab on a private domain or managed infrastructure.

​
What happens after connection

Once the connection is complete, Overcut uses the GitLab account and instance you connected for GitLab-related work in your workspace. This means Overcut can use that GitLab instance to:
  • Access connected repositories
  • Work with issues and merge requests
  • Support GitLab-based workflow activity
  • Respond to supported GitLab events for connected repositories, including issues, issue comments, merge requests, merge request comments, and pipeline activity
If you connected a self-hosted GitLab instance, Overcut continues to use that configured instance for repository access and related GitLab activity in your workflows. Agents can create, remove, and read GitLab issue links. GitLab supports three link types: relates_to, blocks, and is_blocked_by (agents can inspect the available types before linking). Cross-project linking works when GitLab allows it and the service account can access both projects. See the tools reference for how linked relationships work across providers.

​
Using GitLab in Your Workflows

Once connected, GitLab repositories will appear as available sources when you:
  • Add a Source to a workflow
  • Configure a Trigger that monitors GitLab events
  • Set up Actions that work with code or issues

​
Permissions

The GitLab OAuth integration requests the following scope:

​
API access

  • api: Access needed to work with repositories, issues, merge requests, and related GitLab actions in Overcut