---
title: GitLab
slug: docs/gitlab
createdAt: 2026-10-20T10:00:00.000Z
---

Connect a GitLab account to Archbee, then sync its projects to doc spaces. Archbee works with projects on gitlab.com. Self-managed GitLab instances are not supported.

Only organization admins in Archbee can connect GitLab.

## Connect GitLab

Archbee connects to GitLab with OAuth, as the GitLab user who signs in. It can sync the projects that this user is a member of. To let Archbee add the webhooks that keep spaces in sync, the user needs the Maintainer or Owner role on those projects.

::::WorkflowBlock
:::WorkflowBlockItem
In Archbee, open **Organization Settings** > **[Configurations](https://app.archbee.com/settings/team-integrations)** and click the **GitLab** card (*Connect GitLab account*).
:::

:::WorkflowBlockItem
Click **Connect with OAuth**. GitLab asks you to authorize Archbee to use the API and to read repositories.
:::

:::WorkflowBlockItem
After you authorize Archbee, you return to **Configurations**, and the GitLab card shows **Connected**. Open the card to see your projects, grouped by GitLab group. Click **Refresh GitLab data** to load projects you joined later.
:::
::::

To connect a different GitLab user, open the card and click **Reconnect with OAuth**.

## Create a space from a GitLab project

1. Create a new space and select **Write in GitLab**.
2. In **Select Git Repo**, choose the project. In **Select Branch**, choose the branch Archbee tracks.
3. Click **Add Space**.

You can also click the **+** button (*Create synced space*) next to a project in the GitLab card. Choose a **Space group** and a branch, then click **Create space**.

When the import finishes, Archbee notifies you. If the project has no Archbee config file yet, Archbee also opens a merge request titled **Setup for Archbee-powered Docs** with an `archbee.json` file and starter pages. To configure the project yourself, see [Set up the repository](docId\:fsqc31Wq96DYg7y-vml_H).

## Connect an existing space

1. Open the space's menu and click **Sync with Git App**, then **Sync with GitLab**.
2. Choose the project and the branch.
3. If the project has no `archbee.json` yet, follow **Let's configure your repo**: create the merge request, open it in GitLab, merge it, then click **Check if merged**.
4. Click **Add Space**.

:::hint{type="warning"}
Connecting a space to a project replaces the content of the space with the content of the project. Try it on a copy of the space first.
:::

## Keep the space in sync

Archbee adds a webhook to the project. Each push to the tracked branch starts a sync. While auto-merge is off, which is the default, each push waits for review in Archbee. See [Review incoming git changes](https://www.archbee.com/docs/review-incoming-git-changes).

To change how the space syncs, open **Space settings** > **GitLab Integration**:

- **Git branch** sets the branch Archbee tracks and opens merge requests on. Changing it takes publish rights on the space.
- **Auto-merge pushes** sets whether pushes apply right away or wait for review.
- **Sync from repo** replaces the space with the content of the project right away, even when auto-merge is off.

## Send Archbee drafts to GitLab

::::WorkflowBlock
:::WorkflowBlockItem
Edit your documents as drafts. Click **Publish Space** in the top right corner. In the **Update GitLab MR** row, click **Review & Push to PRs**.
:::

:::WorkflowBlockItem
Review your changes, then click **Push to GitLab MR**. Archbee opens a merge request against the tracked branch, or updates the one it already opened.
:::

:::WorkflowBlockItem
Review and merge the merge request in GitLab. Archbee deletes the drafts that went into it and syncs the merged content. While auto-merge is off, the merged content waits for review in Archbee first.
:::
::::

## Disconnect GitLab

To disconnect one space, open **Space settings** > **GitLab Integration** and click **Remove GitLab integration**.

To disconnect the whole organization, click **Remove Integration** at the bottom of the GitLab card, then confirm. Archbee removes its webhooks from the projects, disconnects every space that synced from GitLab and deletes the stored credentials. The spaces keep their content.

## Differences from GitHub

- Archbee does not import shadow docs from GitLab. See [Code base as Shadow docs](https://www.archbee.com/docs/code-base-as-shadow-docs).
- Each sync downloads every file in the docs folder again, so syncs of large projects take longer than on GitHub.
- Archbee connects as one GitLab user, not as an app installed on a group.