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

​
Connection options

You can connect GitLab to Overcut in two ways:

GitLab.com

Use this option if your repositories are hosted on GitLab.com. You only need the service account and GitLab.com sign-in.

Self-hosted GitLab

Use this option if your team runs GitLab on your own domain or private infrastructure. You will enter your instance URL and your instance-specific OAuth application credentials before authorizing access.

​
Choose GitLab.com or self-hosted GitLab

In Overcut, go to Integrations and start the GitLab connection flow.
  • Leave Connect to a self-hosted GitLab instance turned off if you use GitLab.com
  • Turn on Connect to a self-hosted GitLab instance if you use your own GitLab domain or private deployment
When you choose the self-hosted option, Overcut asks for three fields before you continue:
  • Instance URL
  • OAuth Application ID
  • OAuth Application Secret
These values are specific to your GitLab instance and are different from the standard GitLab.com flow.

​
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, choose GitLab, enable Connect to a self-hosted GitLab instance, and enter:
  • Instance URL
  • OAuth Application ID
  • OAuth Application Secret
Then select I am ready to continue.
4

Authorize access in your GitLab instance

Overcut redirects you to your own GitLab instance for authorization.Sign in as the dedicated service account if needed, review the request, and approve access to complete the connection.

​
Verify the connection

After authorization, confirm the connection is working as expected:
  • 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.

​
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 redirect to your own GitLab domain rather than GitLab.com
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

Connection typeWhat you enter in OvercutWhere authorization happens
GitLab.comNo instance-specific fieldsGitLab.com
Self-hosted GitLabInstance URL, OAuth Application ID, and OAuth Application SecretYour GitLab instance
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