> ## Documentation Index
> Fetch the complete documentation index at: https://www.oplane.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a self-managed GitLab instance

> Add a self-managed GitLab integration in Oplane organisation settings so your workspaces can connect repositories from a self-hosted GitLab instance.

If your team runs its own GitLab server instead of GitLab.com, add it as an organisation integration so your workspaces can connect repositories from it. You configure the connection once at the organisation level using a GitLab OAuth application, and then anyone in the organisation can subscribe to projects on that instance the same way they would for GitLab.com.

<Frame caption="Connecting a self-managed GitLab instance, start to finish. Click to replay.">
  <video
    autoPlay
    muted
    playsInline
    controls={false}
    disablePictureInPicture
    disableRemotePlayback
    controlsList="nodownload noplaybackrate nofullscreen noremoteplayback"
    className="w-full aspect-video rounded-xl"
    style={{ cursor: "pointer", pointerEvents: "auto" }}
    src="https://mintcdn.com/oplane-6a173d70/mVqlsUo57LMT2xBO/images/integrations/gitlab-flow.webm?fit=max&auto=format&n=mVqlsUo57LMT2xBO&q=85&s=6e1cd1905fed7b71a618d7651669a500"
    onEnded={(e) => {
  const v = e.currentTarget;
  const plays = (Number(v.dataset.plays) || 0) + 1;
  v.dataset.plays = String(plays);
  if (plays < 3) {
    v.currentTime = 0;
    v.play();
  }
}}
    onClick={(e) => {
  const v = e.currentTarget;
  v.dataset.plays = "0";
  v.currentTime = 0;
  v.play();
}}
    data-path="images/integrations/gitlab-flow.webm"
  />
</Frame>

<Info>
  You need the **Owner** role on the Oplane organisation to manage integrations, and administrator access on your GitLab instance to create the recommended instance-wide OAuth application.
</Info>

## Open the Integrations tab

Open the organisation switcher in the top-right corner (it shows your current organisation name) and click **Org Settings**.

<Frame>
  <img src="https://mintcdn.com/oplane-6a173d70/GQK91gqL1oAEp0r4/images/integrations/org-settings-menu.png?fit=max&auto=format&n=GQK91gqL1oAEp0r4&q=85&s=134638e73d5c8a762e1405e1cc65ecb3" alt="Organisation switcher menu open on the dashboard with the Org Settings option" width="2084" height="1172" data-path="images/integrations/org-settings-menu.png" />
</Frame>

In Settings, open the **Integrations** tab. Before you add anything, the tab shows the integrations you can configure. Self-managed GitLab is currently the only one.

<Frame>
  <img src="https://mintcdn.com/oplane-6a173d70/GQK91gqL1oAEp0r4/images/integrations/empty-state.png?fit=max&auto=format&n=GQK91gqL1oAEp0r4&q=85&s=7e8ed7a16899c4a84e5801ed95fe6f29" alt="Integrations tab in organisation settings showing the Self-managed GitLab option" width="2084" height="1172" data-path="images/integrations/empty-state.png" />
</Frame>

## Create a GitLab OAuth application

Oplane connects to your instance through an OAuth application that you create in GitLab. Create it before you fill in the form in Oplane, because you'll need the application ID and secret it generates.

<Steps>
  <Step title="Open the application settings in GitLab">
    Sign in to your GitLab instance and open **Admin Area > Applications**. We recommend an instance-wide application because it belongs to your GitLab instance rather than to a single person.

    <Warning>
      A personal application under **User Settings > Applications** is less reliable, because it belongs to one GitLab account. If that account is blocked or removed, the application goes with it and every linked account on the instance stops working in Oplane until you register a new one.
    </Warning>
  </Step>

  <Step title="Add a new application">
    Create a new application and give it a recognisable name such as `Oplane`. Set the **Redirect URI** to exactly this value:

    ```
    https://gravity.oplane.io/api/web/auth/federation/callback
    ```

    Under **Scopes**, select `read_user` and `api` so Oplane can read the signed-in user and work with projects and merge requests on your behalf.
  </Step>

  <Step title="Set the application options">
    Keep **Confidential** enabled. For an instance-wide application, also tick **Trusted** so your users skip GitLab's authorization screen. Leave the other options off, including **Device authorization grant**, then save the application.
  </Step>

  <Step title="Copy the credentials">
    After you save, GitLab shows the **Application ID** and **Secret**. Copy both now, since GitLab only shows the secret once.
  </Step>
</Steps>

## Add the integration in Oplane

Back in Oplane, click the **Self-managed GitLab** option to open the configuration form.

<Steps>
  <Step title="Enter your GitLab host">
    In **GitLab host**, enter the hostname of your instance, for example `gitlab.example.com`. The `https://` prefix is added for you, so leave it out of the field.
  </Step>

  <Step title="Paste the application ID and secret">
    Paste the **Application ID** and **Secret** from the GitLab OAuth application you created. If you're not sure how to generate these, click **Need help? See how to create a GitLab OAuth application** at the top of the form.

    <Frame>
      <img src="https://mintcdn.com/oplane-6a173d70/GQK91gqL1oAEp0r4/images/integrations/add-gitlab.png?fit=max&auto=format&n=GQK91gqL1oAEp0r4&q=85&s=96ca511938564f18d4399006addabcfb" alt="Self-managed GitLab configuration form with host, application ID, and secret filled in" width="2084" height="1966" data-path="images/integrations/add-gitlab.png" />
    </Frame>
  </Step>

  <Step title="Save the integration">
    Click **Save Integration**. The integration now appears in the list on the Integrations tab, and your workspaces can start connecting projects from this instance.

    <Frame>
      <img src="https://mintcdn.com/oplane-6a173d70/GQK91gqL1oAEp0r4/images/integrations/connected.png?fit=max&auto=format&n=GQK91gqL1oAEp0r4&q=85&s=ad23c274308dd93f7370add5fabaa1ae" alt="Integrations tab showing a connected self-managed GitLab instance" width="2084" height="1966" data-path="images/integrations/connected.png" />
    </Frame>
  </Step>
</Steps>

To add another instance later, click **Add integration** in the top right of the tab.

## Connect repositories from your instance

Once the integration is saved, connecting a self-hosted project works the same as [connecting a GitLab.com project](/docs/gitlab-setup). When you add a source to a workspace and continue with GitLab, your self-managed instance is available alongside GitLab.com, so you can pick the group and project you want.

## Manage or remove an integration

Click an integration in the list to open its detail page. From there you can review the **Application ID**, rotate the stored credentials with **Change** if you regenerate them in GitLab, or remove the connection under **Danger Zone**.

<Frame>
  <img src="https://mintcdn.com/oplane-6a173d70/GQK91gqL1oAEp0r4/images/integrations/manage.png?fit=max&auto=format&n=GQK91gqL1oAEp0r4&q=85&s=d88fce3acc4a8a1e9a6dda4c0050dba5" alt="Self-managed GitLab integration detail page with application ID, secret, and Danger Zone" width="2084" height="1966" data-path="images/integrations/manage.png" />
</Frame>

Deleting an integration disconnects it, so workspaces can no longer connect new repositories from that instance. You can reconfigure it later by adding it again with the same credentials.

## Troubleshooting

### The GitLab host field shows an error

Enter only the hostname, such as `gitlab.example.com`, without the `https://` prefix or a trailing path. The prefix is part of the field itself.

### Saving fails or the connection is rejected

Double-check that the **Application ID** and **Secret** match the OAuth application in GitLab, and that the application uses the `read_user` and `api` scopes with **Confidential** enabled. The **Redirect URI** must be exactly `https://gravity.oplane.io/api/web/auth/federation/callback`. If you regenerated the secret in GitLab, open the integration and use **Change** to store the new value.

### No projects appear when connecting a workspace

Confirm the integration is listed on the Integrations tab and that your GitLab account has access to the projects you expect. Oplane lists only projects where you are Maintainer or Owner, since that access level is required to create a project access token.

## Report a bug

If something isn't working as expected and isn't covered above, reach out to us at [support@oplane.io](mailto:support@oplane.io). Include what you were doing, what you expected, and what happened instead. Screenshots of the settings page are helpful.