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

# GitLab

> Integrate your GitLab projects with the subgraphs in WunderGraph Hub

The GitLab integration is a powerful feature that bridges your GraphQL schema management with your development workflow. This integration allows you to automatically sync schema in proposals with GitLab projects, streamlining your development process and keeping your schemas in sync with your codebase.

## Setup and Configuration

<Steps>
  <Step title="Navigate to the &#x22;Integrations&#x22; tab under &#x22;Settings&#x22;." />

  <Step title="Click the &#x22;Connect GitLab&#x22; button.">
    <img src="https://mintcdn.com/wundergraphhub/-jQI1JMT_pnsyeFl/images/gitlab/integration_page.png?fit=max&auto=format&n=-jQI1JMT_pnsyeFl&q=85&s=953afb649cec0031099b2baf9d4e7fe8" alt="GitLab Integration" width="2880" height="1684" data-path="images/gitlab/integration_page.png" />
  </Step>

  <Step title="Choose your GitLab instance type.">
    A dialog will appear asking you to choose your GitLab instance type. WunderGraph Hub supports two connection flows:

    <Tabs>
      <Tab title="GitLab.com (Cloud)">
        Use this option if your repositories are hosted on [gitlab.com](https://gitlab.com).

        1. Select the **GitLab.com** tab in the dialog.
        2. Click **Connect** — you will be redirected to GitLab.com to authorize the WunderGraph Hub application.
        3. Grant the necessary permissions (`api`, `read_repository`, `write_repository`).
        4. Once authorized, you will be redirected back to WunderGraph Hub.
      </Tab>

      <Tab title="Self-Hosted / GitLab Enterprise">
        Use this option if your organization runs a self-hosted or enterprise GitLab instance.

        Before connecting, you need to create a GitLab OAuth application on your instance. See the [GitLab App Setup guide](./gitlab-app-setup) for step-by-step instructions.

        1. Select the **Self-Hosted** tab in the dialog.
        2. Enter your **GitLab Instance URL** (e.g., `https://gitlab.example.com`). Must use HTTPS.
        3. Enter the **Application ID (Client ID)** from your GitLab OAuth application.
        4. Enter the **Secret (Client Secret)** from your GitLab OAuth application.
        5. Click **Connect** — you will be redirected to your GitLab instance to authorize the application.
        6. Once authorized, you will be redirected back to WunderGraph Hub.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Navigate to any of your graphs, click the dropdown in the top-left corner, select &#x22;Integrations&#x22;, then select &#x22;Git&#x22;.">
    <img src="https://mintcdn.com/wundergraphhub/-jQI1JMT_pnsyeFl/images/git/settings.png?fit=max&auto=format&n=-jQI1JMT_pnsyeFl&q=85&s=eeb3ef873baef06c3495baa00f341da3" alt="Graph GitLab Settings" width="1502" height="865" data-path="images/git/settings.png" />
  </Step>

  <Step title="Select the GitLab projects you want to connect to each subgraph." />

  <Step title="Click &#x22;Save Mappings&#x22; to connect the projects.">
    This will create initialization MRs in all selected projects with the respective subgraph schema.

    <img src="https://mintcdn.com/wundergraphhub/-jQI1JMT_pnsyeFl/images/git/mappings.png?fit=max&auto=format&n=-jQI1JMT_pnsyeFl&q=85&s=6824c8f61ee7891fea130573380493a7" alt="Graph GitLab Mappings" width="800" height="955" data-path="images/git/mappings.png" />
  </Step>
</Steps>

## Merge Request Lifecycle

The GitLab integration automatically synchronizes merge request states with your schema proposal status, ensuring your development workflow stays aligned with your schema management process.

**Merge Request State Management:**

| State                | Behavior                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ready for Review** | When a proposal is created in opened state, a merge request is automatically created in "ready for review" state across all mapped projects. |
| **Draft**            | When a proposal is moved to draft state, the merge request transitions to draft state.                                                       |
| **Closed**           | When the proposal is closed, the corresponding merge request is also closed.                                                                 |
| **Reopened**         | If a closed proposal is reopened, the merge request is also reopened.                                                                        |

## How It Works

### Streamlined Development Workflow

The GitLab integration eliminates the friction between schema design and implementation by automatically creating branches in your mapped projects whenever a schema proposal is made. This means developers can immediately start implementing changes without manual setup.

### Automatic Merge Request Creation

When a schema proposal is created in the hub, the integration automatically:

* Creates a new branch in the mapped project
* Stores the proposed schema files directly in the branch
* Creates a merge request with the schema changes on new changes after creating a proposal or by opening the proposal.