​
What You Can Do

With GitLab connected, Overcut agents can:
  • Access Repositories: Clone, read, and modify code in your GitLab repositories
  • Manage Issues: Create, update, and comment on GitLab issues
  • Handle Merge Requests: Review, comment on, and manage merge requests
  • Code Operations: Clone repositories, create branches, and perform git operations
  • Webhook Triggers: Automatically start workflows based on GitLab events
  • Repository Configuration: Configure agent behavior per repository

​
Prerequisites

  • A GitLab account (GitLab.com or self-hosted) with access to repositories you want to connect
  • An active Overcut workspace
  • A dedicated GitLab service account with Maintainer or Owner permissions to create webhooks and be able to read and write to your repositories and issues

​
Setup Overview

Unlike other providers that support app identities, GitLab requires using the permissions of the user who authorizes the integration. Therefore, GitLab integration requires a dedicated service account to ensure consistent bot identity and prevent operational issues. Using personal accounts leads to attribution confusion, infinite loops, and integration failures when team members leave. Service Account Advantages:
  • Consistent Bot Identity: All operations appear under a single, recognizable bot user
  • Loop Prevention: Overcut can reliably filter out its own activity
  • Independence: Integration survives team member departures and role changes
  • Clear Attribution: Team members know which actions were automated vs. manual
  • Centralized Management: Single account works across all projects and groups
  • Token Stability: OAuth tokens remain valid regardless of personnel changes

​
Setup Steps

1

Create GitLab Service Account

Create a dedicated service account to act as the Overcut bot identity.

​
For GitLab.com or Self-Hosted GitLab:

  1. Create a new user account:
    • Username: overcut-bot (or similar)
    • Name: Overcut Bot
    • Email: Use a shared/team-managed email (e.g., overcut-bot@yourcompany.com)
  2. Add the service account to your projects/groups:
    • Add the bot user to each project or group where you want Overcut to operate
    • Assign Maintainer or Owner role to ensure sufficient permissions
    • This allows the bot to create webhooks, access code, and manage issues
Using a dedicated service account ensures that Overcut’s access remains stable even if team members leave, and provides a clear, consistent identity for all bot operations.
2

Authorize Overcut with the Service Account

Connect the service account to Overcut using OAuth.
  1. Sign in to GitLab as the overcut-bot service account
  2. Using the same browser, in your Overcut workspace, go to Settings → Integrations → Git & Ticket
  3. Click Connect GitLab
  4. You’ll be redirected to GitLab’s authorization screen
  5. Approve the Overcut application with the required scopes
  6. Complete the OAuth flow to link the service account to Overcut
This establishes the connection between Overcut and GitLab using the bot account’s credentials.
3

Verify Connection

Confirm that the integration is working properly.
  1. Check that your GitLab repositories appear in Overcut’s repository list
  2. Verify that you can select GitLab projects when creating workflows
  3. Test webhook functionality by creating a simple workflow trigger
The connection is now complete and ready for use in your workflows.

​
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 scopes:

​
API Access

  • api: Full API access to repositories, issues, and merge requests
  • This comprehensive scope enables Overcut to:
    • Read and write repository contents
    • Create and manage issues
    • Review and comment on merge requests
    • Create webhooks for event notifications
    • Access project and group information