Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

Connect to GitLab with OAuth

Enterprise plans

Deprecated

Integrate self-hosted GitLab instances with Projects to access repositories, create pull requests, and collaborate within the existing GitLab infrastructure.

Prerequisites

Before you begin, make sure to have:

  • An Enterprise Builder account.
  • A self-hosted GitLab instance.
  • Admin access to your GitLab instance.
  • Repository access permissions for connecting users.

Step 1: connect to the GitLab instance

To connect your GitLab instance:

  1. Go to Projects and click the Connect Repo dropdown.
  2. Select GitLab from the Git providers list.
  3. For self-hosted instances, click Connect to your own GitLab instance.

This opens the Connect Self-hosted GitLab Repository window with setup options.

The video below shows connecting with Gitlab instance and available methods:

Step 2: create a GitLab OAuth application

Create an OAuth application using one of these methods:

Admin UI (recommended)

To create the OAuth application using GitLab's Admin interface from your GitLab instance:

  1. In GitLab, go to User Settings > Applications.
  2. Click Add new application.
  3. In the Name field, enter Builder.io.
  4. In the Redirect URI field, enter https://builder.io/api/v1/projects/gitlab/callback.
  5. Uncheck Confidential.
  6. In the Scopes section, select api, read_api, read_user, read_repository, write_repository checkboxes.
  7. Click Save application.

The video below shows the application creation process in your self-hosted GitLab instance:

CLI

If you prefer a command-line setup:

  1. Go to GitLab Settings > Access Tokens.
  2. Create a new token and select api and read_api scopes.
  3. Copy the generated token.

Run the below command, replace YOUR_ADMIN_TOKEN with the actual token, and gitlab.example.com with the GitLab URL:

curl -X POST \ -H "PRIVATE-TOKEN: YOUR_ADMIN_TOKEN" \ -d "name=Builder.io" \ -d "redirect_uri=https://builder.io/api/v1/projects/gitlab/callback" \ -d "scopes=api read_api read_user read_repository write_repository" \ -d "confidential=true" \ https://gitlab.example.com/api/v4/applications

The response from the curl contains the application_id and secret values.

Step 3: enter GitLab credentials

Enter your OAuth application credentials from Step 2 to connect Builder with the GitLab instance:

  1. In the Connect Self-hosted GitLab Repository window, enter the GitLab Host URL, and your Application ID.
  2. Make sure that Confidential is set to No.
  3. Click Save Configuration.

Builder saves the configuration and automatically redirects to the Connect Self-hosted GitLab Repository page of the Projects.

The video below shows the GitLab enterprise configuration process:

Step 4: authorize and connect repositories

Complete the user authorization for repository access:

  1. On the Connect Self-hosted GitLab Repository page, you'll see your space is connected to GitLab Enterprise.
  2. Click Connect GitLab Enterprise.
  3. A popup window opens for OAuth authentication with your GitLab instance.
  4. Authorize Builder.io in the popup.
  5. Select a repository to connect.

Step 5: make changes and submit pull requests

Follow these steps to work with your connected repository:

  1. Make changes to the repository with Projects.
  2. Click Send PR to create a pull request.
  3. Review and merge the pull request in your GitLab instance.

For more information on the workflow, see Projects Overview and Create a pull request.

Technical details

This section explains how the GitLab on-premises integration works behind the scenes, including configuration storage, API communication, and security implementation.

Configuration storage

Builder stores all GitLab configuration in your organization settings, including the host URL, application credentials, and tokens. This configuration persists across sessions and users.

API integration

Builder communicates with your GitLab instance through REST API integration. All API calls are directed to your specified GitLab host, providing complete support for standard GitLab repository operations.

Security

The integration uses OAuth 2.0 authentication with secure token storage and management. Permissions are scoped to provide only the minimal access required for Builder functionality.

Fix connection issues

Review these solutions for common connection problems.

Cannot connect to GitLab instance:

  • Verify your GitLab host URL is correct and accessible.
  • Confirm the OAuth application exists and has the correct scopes.
  • Check that the application is enabled.

Authorization fails:

  • Verify the user has the necessary GitLab permissions.
  • Confirm OAuth application settings are correct.
  • Check that the redirect URI matches exactly.

Repositories not visible:

  • Verify the user has repository access in GitLab.
  • Confirm application has correct permissions.
  • Check if the GitLab instance allows repository integration.

What's next

Explore these related topics:

Was this article helpful?