Integrate self-hosted GitLab instances with Projects to access repositories, create pull requests, and collaborate within the existing GitLab infrastructure.
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.
Begin connecting your GitLab instance:
- Go to Projects and click the Connect Repo dropdown.
- Select GitLab from the Git providers list.
- 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:
Create an OAuth application using one of these methods:
To create the OAuth application using GitLab's Admin interface from your GitLab instance:
- On the sidebar, go to Admin Area > Applications.
- Click Add new application.
- In the Name field, enter
Builder.io. - In the Redirect URI field, enter
https://builder.io/api/v1/projects/gitlab/callback. - Select the Confidential checkbox.
- In the Scopes section, select
api,read_api,read_user,read_repository,write_repositorycheckboxes. - Click Save application.
- Copy the Application ID and Secret.
The video below shows the application creation process in your self-hosted GitLab instance:
If you prefer a command-line setup:
- Go to GitLab Settings > Access Tokens.
- Create a new token and select
apiandread_apiscopes. - 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/applicationsThe response from the curl contains the application_id and secret values.
Enter your OAuth application credentials from Step 2 to connect Builder with the GitLab instance:
- In the Connect Self-hosted GitLab Repository window, enter GitLab Host URL, Application ID, and Application Secret.
- 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:
Complete the user authorization for repository access:
- On the Connect Self-hosted GitLab Repository page, you'll see your space is connected to GitLab Enterprise.
- Click Connect GitLab Enterprise.
- A popup window opens for OAuth authentication with your GitLab instance.
- Authorize Builder.io in the popup.
- Select a repository to connect.
Follow these steps to work with your connected repository:
- Make changes to the repository with Projects.
- Click Send PR to create a pull request.
- Review and merge the pull request in your GitLab instance.
For more information on the workflow, see Projects Overview and Create a pull request.
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.
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.
Explore these related topics: