> ## Documentation Index > Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt > Use this file to discover all available pages before exploring further. # Connect your project to GitLab > Connect your Lovable project to GitLab.com or a self-managed GitLab instance for code backup, collaboration, and deployment. [GitLab](https://gitlab.com/) is a platform for storing, managing, and sharing code. It provides version control, CI/CD pipelines, code reviews via merge requests, and integrations with popular deployment tools. With GitLab, your app can: * **Back up your code:** Store your project safely outside Lovable. * **Collaborate easily:** Invite developers, use merge requests, branches, and code reviews. * **Sync automatically:** Edits in Lovable appear in GitLab, and changes in GitLab sync back on the default branch (typically `main`). * **Work locally:** Clone, edit, and commit in your IDE while keeping your project synced. * **Deploy anywhere:** Self-host or deploy to alternative platforms. See [Deployment, hosting, and ownership options with Lovable Cloud](/tips-tricks/deployment-hosting-ownership). * **Use your company's infrastructure:** With GitLab Self-Managed, keep your code entirely within your organization's own servers. You don't need GitLab to use Lovable. Many users build and launch entirely within Lovable. ## How GitLab connections work Lovable supports two GitLab connection types through a single unified connector: * **GitLab.com** is the hosted service managed by GitLab Inc. * **GitLab Self-Managed** lets you connect to a GitLab instance that your organization runs on its own servers. When you open GitLab, you choose which type to set up. Both types support the same two-way sync between Lovable and your GitLab repository. Within your Lovable workspace: * You can create multiple GitLab connections. * Each connection is linked to a namespace (personal account or group) on a GitLab instance. * You can connect multiple namespaces from the same GitLab account or instance. * Each Lovable project can be linked to one repository within one of those namespaces. ## How to connect GitLab Workspace **admins** and **owners** can manage GitLab, which includes adding connections and linking or unlinking projects. Users with **editor** role can link or unlink projects. ### Prerequisites * A GitLab account on [gitlab.com](https://gitlab.com) or on your self-managed instance. * Lovable workspace admin or owner role. * For GitLab Self-Managed: admin access to your GitLab instance to create an OAuth application, and network access from Lovable's IP ranges. ### Before you connect * **Single source of truth:** When connected, your code lives in GitLab, not separately in Lovable. * **Two-way sync:** Edits in Lovable appear in GitLab, and vice versa. * **Stable repo path:** The connection depends on the exact GitLab project name, namespace, and instance URL. Don't rename, move, or delete your GitLab project after connecting. Doing so will break the sync, and Lovable won't be able to update your project. ### Step 1: Set up a GitLab connection GitLab.com is the hosted service managed by GitLab Inc. Open **Settings** → **Git** → **GitLab**. Click **Add connection** and select **GitLab.com**. A popup opens to GitLab's authorization page. Sign in and **authorize Lovable** to access your GitLab account. Lovable requests the `api` scope, which is required to create projects, configure webhooks, manage branches, and open merge requests. Choose where your project repositories should live: * Select your **personal account** or one of your **GitLab groups**. * Click **Connect** next to the namespace you want to use. You can connect multiple namespaces (personal account and groups) from the same GitLab account. You cannot connect the same personal account or group more than once. GitLab Self-Managed is intended for organizations that run their own GitLab server and need their code to stay within internal infrastructure. Open **Settings** → **Git** → **GitLab**. Click **Add connection** and select **GitLab Self-Managed**. Lovable needs to reach your GitLab instance to sync code and receive webhook events. The setup wizard displays the IP CIDR ranges you need to allowlist if your instance is protected by a firewall. Copy each one and add it to your network firewall or GitLab's IP allowlist settings. In your GitLab instance, go to **Admin Area → Applications** (or **Settings → Applications** for a user-level app) and create a new application: * **Name:** Lovable (or any descriptive name) * **Redirect URI:** Use the URI shown in the Lovable setup wizard (for example, `https://lovable.dev/gitlab/callback`) * **Scopes:** `api` * **Confidential:** Yes Save the application and note the **Application ID** and **Secret**. Keep your Application Secret confidential. It grants access to your GitLab instance on behalf of your users. Back in the Lovable setup wizard, fill in: * **GitLab URL:** Your instance URL (e.g., `https://gitlab.yourcompany.com`) * **Application ID:** The client ID from the OAuth app you created * **Application secret:** The client secret from the OAuth app * **Group path (optional):** If you want to restrict access to a specific group, enter the group path (for example, `my-org/my-team`) Click **Continue**. A popup opens to your self-managed GitLab instance's authorization page. Sign in and authorize Lovable. Lovable requests the `api` scope. Choose between your **personal account** or one of your **GitLab groups** within the instance, then click **Connect**. ### Step 2: Connect a project to GitLab Once you have an active GitLab connection, **editors and above** can link a Lovable project to a GitLab repository. Each Lovable project can have **one linked repository**. Open **Settings** → **Git** → **GitLab** and click **Connect project**, or click the GitLab icon in the top-right corner of your project. Select the namespace (personal account or group) where the repository should be created. Confirm the transfer. A new GitLab project is created, and two-way sync begins automatically. ## Disconnect a project from GitLab Workspace admins and owners can disconnect (unlink) **any project** from GitLab at any time in the project's GitLab settings. When you disconnect: * **Sync stops:** The two-way connection between Lovable and GitLab ends. * **Your repository stays on GitLab:** It remains intact with all history and files. * **Your code stays in Lovable:** Future changes are stored only inside Lovable. If you reconnect later: * A **new GitLab repository** is created using your latest Lovable code. * Your **original repository** stays on GitLab but is no longer linked to Lovable. You can't disconnect a project if Lovable can't reach the GitLab repository (for example, if it was renamed, moved, or deleted). ## Limitations GitLab currently does not support: * Importing an existing GitLab repository into Lovable. You can only export from Lovable to GitLab. * Syncing branches other than the default branch (usually `main`). * Reconnecting to the same repository after disconnecting. A new repository is created on reconnect. ## How to unlink projects from a GitLab connection Editors and above can remove specific projects from a connection without deleting the connection entirely. The connection will remain available for other projects. To unlink projects: Open **Settings**, then go to **Git**, and select **GitLab**. Open the connection you want to manage. Under **Linked projects**, check the projects you want to unlink. Click **Unlink projects** and confirm. When unlinked, those projects will no longer have access to GitLab through this connection. If a project needs GitLab again, you can link it to any available connection. ## How to delete a GitLab connection Workspace admins and owners can delete GitLab connections. Deleting a connection is permanent and cannot be undone. It will remove the credentials from all linked projects, and any apps using this connection will stop working until a new connection is added. Before deleting, review the **Linked projects** section to see which projects are currently using the connection. To delete a connection: Open **Settings**, then go to **Git**, and select **GitLab**. Open the connection you want to remove. Review the **Linked projects** section. Under **Delete this connection**, click **Delete** and confirm. ## FAQ No. Just connect and authorize. GitLab will safely store your code. You only need to learn GitLab's features if you want to do more advanced things like branching, merge requests, or CI/CD pipelines. Your browser probably blocked the GitLab login popup. Allow popups for Lovable, then try again. The connection will break. Your project will stop syncing, and you won't be able to edit it in Lovable. To fix this, restore the project to its original path and name in GitLab. If the project was deleted, restore it from GitLab's admin panel. The connection will break. Your project will stop syncing, and you won't be able to edit it in Lovable. To fix this, revert to the original GitLab username or group path. You can't change the linked GitLab account once connected. As a workaround: 1. Unsync the project from the current GitLab connection (there's a disconnect option in settings) 2. Delete the existing connection if you want a different personal account (workspace allows only one personal GitLab account) 3. Create a new connection with the correct GitLab account 4. Reconnect the project to the new connection Yes. You can disconnect projects from GitLab at any time in your project's GitLab settings. Your repository stays on GitLab, but syncing stops. If you reconnect later, a new repository is created. No. You can only export from Lovable to GitLab, not the other way around. Lovable only syncs the **default branch** (usually `main`). Merge your branch into `main` to see it inside Lovable. Yes. You can connect multiple namespaces (your personal account and multiple groups) from the same GitLab account or self-managed instance. Each Lovable project is then linked to one repository within one of those namespaces. **GitLab.com** is the hosted service managed by GitLab Inc. **GitLab Self-Managed** is a GitLab instance that your organization runs on its own servers. Self-Managed requires you to create an OAuth application in your instance and allowlist Lovable's IP ranges. Lovable requests the `api` scope, which is the minimum required to create projects, configure webhooks, manage branches, and open merge requests on your behalf. Only if Lovable's public IP ranges can reach your instance. Lovable needs network access to your GitLab server to push code and receive webhook events. If your instance is strictly internal and cannot be reached from Lovable's IPs, reach out to Sales to discuss a potential custom integration.