Self-host GitLab EE/CE

Prerequisites

  • You should be the Workspace Admin to be able to see the GitOps sidebar item and add Git Provider.
  • You should have a project created in GitLab.
  • If your Bytebase instance resides in the same private network as your GitLab instance, you will need to enable Allow requests to the local network from webhooks and integrations. Otherwise, you will get the error: Failed to create webhook xxx, status code: 422 for GitLab. View details here.

Step 1 - Setting up

Go to Settings from the top nav bar, select GitOps under Workspace, and then click Add a Git provider.

add-git-provider

Fill in the URL where the GitLab instance is running.

add-git-provider-steps

Step 2 - OAuth application info

warning

In this step, you need to register "Bytebase" as a GitLab instance-wide OAuth application. This can only be done by a GitLab instance admin. If you are not, you will need to ask the admin to follow Step 2.1 to register the application and provide the Application ID and Secret. Then you may continue onwards from Step 2.2.

warning

Please make sure you are configuring the GitLab external_url correctly, the host:port must exactly matches the one accessed by Bytebase. It's called external_url because that's how external systems like Bytebase reaches the GitLab instance.

A common mistake is when a user misconfigures the port when using port forwarding. e.g. GitLab is running on port 7890, while it's exposed to the public on port 7891. In this case the external_url should be https://example.com:7891 instead of https://example.com:7890.

Step 2.1 - Register GitLab instance-wide OAuth application (performed by GitLab Admin)

Login the GitLab instance specified in Step 1 as an Admin user. The admin user will see a wrench icon on the top nav bar like below:

gitlab-admin-area

Go to "Applications" from the sidebar, then click "New application" button.

vcs-gitlab-step

Fill in the form with the provided info on the Bytebase setup wizard.

vcs-gitlab-step

Register info:

  • Name: can be other names than "Bytebase", as long as the GitLab admin can identify this application is for "Bytebase" later
  • Redirect URI: begins with the host:port where the Bytebase console is running, and followed by /oauth/callback. This is the URI GitLab uses to callback Bytebase during the OAuth flow
  • Trusted: Yes
  • Confidential: Yes
  • Scopes: api

Click the "Submit" button after filling the info on GitLab and you will see a created application, like below:

vcs-gitlab-step

Step 2.2 - Verify setup

Fill in the Application ID and Secret onto the corresponding fields on the Bytebase setup wizard:

vcs-gitlab-step

After you click "Next", Bytebase will kick off an OAuth flow to verify the setup. If you are not currently logged into the GitLab instance used in the setup. You will be prompted to login to complete the OAuth.

info

If you get an error in the OAuth popup window. Please double-check the following info:

  1. The Redirect URI of the registered GitLab application matches exactly to the Redirect URI shown on the Bytebase wizard.
  2. The Application ID and Secret of the registered GitLab application matches exactly to the filled Application ID and Secret on the Bytebase wizard.
  3. GitLab is network accessible from Bytebase instance. e.g. If you run Bytebase and GitLab on the same host, and Bytebase runs inside docker, Bytebase needs to use the host IP instead of 127.0.0.1 to reach GitLab.

Step 3 - Confirm and add

When everything is setup properly, you will be informed that the setup is correct. Click "Confirm and add".

vcs-gitlab-step

Now you have successfully added a Git provider, developers can now link their Bytebase projects with one of their owned repositories from this Git provider.

Step 4 - Allow requests to the local network from webhooks

If your Bytebase instance resides in the same private network as your GitLab instance, you will need to enable Allow requests to the local network from webhooks and integrations. Otherwise, you will get the error: Failed to create webhook xxx, status code: 422 for GitLab. View details here.

References

  1. GitLab instance-wide applications. For GitLab, this is the OAuth application type Bytebase needs to register.
Edit this page on GitHub

Subscribe to Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.