---
title: GitLab Integration
description: Learn how to connect your GitLab repositories to Capawesome Cloud to build and automate your app directly from source.
---

# GitLab Integration

Connect your GitLab repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io){:target="_blank"} account and an organization (owner or admin role to manage Git connections).
- A GitLab account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git){:target="_blank"} page and click **Create Git connection**.
2. Select **GitLab** as the provider.
3. Follow the steps below to authenticate with a personal access token.

### Personal access token (PAT)

Paste a token you create on GitLab. This works for GitLab.com and, via the **Server URL** field, self-managed GitLab.

1. Create a GitLab personal access token — choose a **legacy token**, not a **fine-grained** token. Always select the `read_user` scope, plus:
    - For a read-only connection: the `read_api` and `read_repository` scopes.
    - To enable [Automations](../automations/index.md): the `api` scope (it covers both cloning and managing the project's webhooks). Your account also needs the **Maintainer** or **Owner** role on the project.
2. Select **Personal access token (PAT)** as the authentication method and paste the token.
3. For **self-managed GitLab**, enable **Self-hosted or enterprise instance** and enter your server's **Server URL**.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git){:target="_blank"} page and click **Connect Git repository**.
2. Select the GitLab connection.
3. Select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).