> ## 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. # Sync your Lovable project with GitLab > Export and two-way sync your Lovable project code with GitLab.com or a self-managed GitLab instance for code backup, collaboration, and deployment. When you build with Lovable, your project code is stored and managed inside the Lovable platform. [GitLab](https://gitlab.com/) is a platform for storing, managing, and sharing code, with version control, merge requests and code reviews, and CI/CD pipelines. If you want your own copy, plan to collaborate with developers, or move your project elsewhere, you can export and sync your project to GitLab: back up your code, review changes in merge requests, work locally in your IDE, test features on branches, and deploy outside Lovable. With GitLab Self-Managed, you can also keep a copy of your code within your own infrastructure. For the full picture of what Git sync is, how the two-way sync model works across providers, and how to choose between GitHub and GitLab, see the [Git sync overview](/integrations/git-sync-overview). You don't need GitLab to use Lovable. Many users build and launch entirely within Lovable. If you only need a copy of your code, you can download your code directly from Lovable. Open the [Code editor](/features/code-mode) and click **Download codebase** at the bottom of the file tree sidebar (paid plans). ## How GitLab Git sync works Like all [Git sync](/integrations/git-sync-overview), the GitLab integration has two layers: 1. A **workspace connection** 2. A **project repository link** ### Workspace connection A workspace connection authorizes Lovable to access a GitLab namespace (your personal account or a group) through OAuth. Lovable requests the `api` scope, which it needs to create projects, configure webhooks, manage branches, and open merge requests. Workspace connections are shared across the workspace and can be reused by multiple projects. A workspace can contain: * Multiple GitLab connections * Multiple group namespaces from the same GitLab account or instance * One personal-account namespace (a workspace can hold only one personal GitLab account, alongside any number of groups) * Both GitLab connection types (GitLab.com and Self-Managed) ### Project repository link A project repository link connects one Lovable project to one GitLab repository. When connected: * Changes made in Lovable sync to GitLab * Changes pushed to the active GitLab branch sync back into Lovable * Lovable only edits and syncs one branch at a time ### GitLab Git sync connection types Lovable supports two GitLab connection types: * **GitLab.com**\ The hosted service managed by GitLab Inc. You authorize Lovable with your GitLab.com account. * **GitLab Self-Managed**\ A GitLab instance that your organization runs on its own servers. You create an OAuth application in your instance, so credentials remain under your control, and allowlist Lovable's IP ranges. When you add a new connection, you choose which type to set up. Both types support the same two-way sync, branch operations, and merge request creation between Lovable and your GitLab repository. ### Role-based access for GitLab integration | Role | Allowed action | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspace owner or admin only | | | | | | | | | Any workspace member, including external collaborators | View the connection in Workspace settings → Git → GitLab (read-only mode) | ## Create a workspace GitLab connection **Workspace admins and owners** can create workspace connections from: * **Workspace settings → Git → GitLab → Add connection** * [**Project settings → Git**](/features/projects/settings#git-tab) **→ GitLab → Add connection** (if a project has not been connected yet) To set up a new connection, follow the steps for your connection type: GitLab.com is the hosted service managed by GitLab Inc. You need a GitLab account. You can create one for free at [gitlab.com](https://gitlab.com). 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 group namespaces from the same GitLab account, plus your personal account. You cannot connect the same personal account or group more than once, and a workspace can hold only one personal-account connection. GitLab Self-Managed is intended for organizations that run their own GitLab server and need their code to stay within internal infrastructure. This setup requires: * Admin access to your GitLab instance to create an OAuth application * Network access from Lovable's public IP ranges 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 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**. ## Link a project to a GitLab repository When there is an active workspace GitLab connection, **workspace or project admins and owners** can connect a Lovable project to a GitLab repository. * Connecting a project creates a new GitLab repository. The repository is **private by default**, so nobody can see your code unless you change its visibility on GitLab. * Each Lovable project can connect to one repository. Open **Project settings → Git → GitLab**. Under **Connect project**, click **Connect** next to the namespace (personal account or group) where the new repository should be created. Lovable creates a new GitLab repository and starts two-way sync automatically. Don't rename, move, or delete your GitLab project after connecting, and don't rename the GitLab username or group it lives under. Doing so will break the sync, and Lovable won't be able to update your project. ## Manage a project's repository sync After connecting a project to a GitLab repository, you see the following in the project's GitLab settings: * Repository status as **Connected** * Branch picker with active branch name (GitLab branch synced with Lovable) * Clone URLs (HTTPS, SSH) * Option to **View on GitLab** (available from the dropdown) * Option to **Disconnect** (available from the dropdown) Lovable only edits and syncs one branch at a time. By default, this is the repository's default branch (usually `main`). Changes pushed to the currently active branch sync back into Lovable. ### Switch branches 1. Click the branch picker. 2. Search or select a branch. 3. Click the branch to switch. Lovable immediately starts editing and syncing the branch you switched to. You can switch back to the default branch at any time. ### Create a new branch 1. Click the branch picker. 2. Click **+ Create branch** at the bottom of the list. 3. Enter a branch name. Lovable validates it against empty names, invalid characters, and duplicates. Branch names must follow Git naming rules (no spaces, .., leading or trailing dots or dashes, and special characters like \~ ^ : ? \* \[ ] \\). The new branch is created from the **currently active branch** as its source (shown as `Source: ` in the dialog). Lovable automatically switches to the new branch and starts editing and syncing it. The source is your **currently active branch**, not the repository's default branch. If you want to start a new feature branch from `main`, switch to `main` first, then create the new branch. You can't switch branches or create new branches while Lovable is editing the project. ### Clone the repository locally After connecting a project, Lovable provides clone URLs for: * HTTPS * SSH You can clone the repository locally and continue working in your preferred IDE. ### Commit attribution Commits made by Lovable are pushed through the GitLab account that authorized the workspace connection, so GitLab attributes pushes to that user. There is no separate bot identity (unlike the Lovable GitHub app). ### Disconnect a project from GitLab Disconnecting removes the sync relationship between a Lovable project and a GitLab repository. 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 project and its code stay in Lovable.** Future changes are stored only inside Lovable. Disconnecting a project does not remove the workspace connection itself. **Workspace or project admins and owners** can disconnect from the project's GitLab settings: in the active repository connection, open the dropdown, select **Disconnect**, and confirm. If a project needs GitLab again, you can link it to any available connection. If you reconnect later: * Lovable creates a new repository with the current version of your project. * The original repository stays unchanged on GitLab and is no longer linked to Lovable. ## Unlink projects from a workspace GitLab connection **Workspace admins and owners** can remove specific projects from a connection without deleting the connection entirely. The connection remains available for other projects. Open **Workspace settings → Git → GitLab**. Open the connection you want to manage. Under **Linked projects**, check the projects you want to unlink. * Click **Unlink N projects** (where `N` is the number of projects you selected) * Click **Unlink** to confirm When unlinked, those projects no longer sync through this connection. ## Delete a workspace GitLab connection **Workspace admins and owners** can delete GitLab connections. Deleting a workspace GitLab connection: * Removes the connection for all projects * Stops syncing for linked projects * Does not delete repositories on GitLab * Deletes stored credentials Deleting a connection is permanent and cannot be undone. Any projects using this connection stop syncing until a new connection is added and the projects are reconnected. Open **Workspace settings → Git → GitLab**. Select the connection from the list. Review the **Linked projects** section carefully before deleting the connection to avoid unintentionally removing GitLab sync. Under **Delete this connection**, click **Delete** and confirm. ## Limitations The GitLab Git sync integration currently does not support: * Importing existing GitLab repositories into Lovable. You can only export from Lovable to GitLab. * Reconnecting to the same repository after disconnecting. A new repository is created on reconnect. * Connecting the same personal account or group more than once, or more than one personal GitLab account per workspace. * Automatically following repository renames or moves. Unlike GitHub, renaming or moving a GitLab project breaks the sync. ## Troubleshooting Lovable only syncs **one branch at a time,** and that is the branch the project is currently set to in its GitLab repository connection settings. By default this is the repository's default branch (usually `main`). If you pushed commits to a different branch in GitLab, you have two options: * **Merge your changes into the synced branch**. For example, open a merge request from your feature branch into `main` and merge it. Lovable then picks up those commits. * **Switch the synced branch in Lovable**. In your project's GitLab settings, select the branch where your commits live. Lovable starts editing and syncing that branch instead, and your commits will appear. The branch your project was synced to was deleted on GitLab. Lovable automatically switched the project to a new branch called `lovable-fallback` so you can keep editing without errors. Your repository is otherwise untouched. Pick another branch or recreate the original branch. You can leave or delete `lovable-fallback` in GitLab once you've moved on. Your synced branch rejected the push, most often because of protected branch rules or because someone pushed a conflicting change you couldn't be rebased onto. To avoid losing your work, Lovable pushed it to a new `lovable-sync-` branch instead. Open that branch on GitLab, review the changes, and merge them into your protected branch through your usual review process. 1. In GitLab, go to **Settings → Applications** or **Admin Area → Applications**, find the Lovable application, and revoke its access. 2. In Lovable, trigger a sync by making a change in a project linked to your GitLab instance (or wait for the next one). The connection will move into a "needs reconnect" state. 3. In Lovable, as a workspace admin, in the GitLab connection, select **Reconnect** and sign into GitLab again. ## FAQ Files you push from your own computer sync into Lovable (up to GitLab's own limits), but Lovable itself cannot save files larger than **10 MB** into your project: any Lovable edit that touches a file over 10 MB fails. For large media, ask Lovable to "Migrate large files to CDN assets". See the [chat page FAQ](/features/projects/chat) for details. Projects created by Lovable are **private by default**, on every plan. Nobody can see your code on GitLab unless you change the project's visibility yourself in GitLab's settings. 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. Disconnect the project from the current GitLab connection (there's a disconnect option in the project's GitLab settings) 2. Delete the existing connection if you want a different personal account (a 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 A new repository is created. The original repository stays on GitLab but is no longer linked to Lovable. Yes. Workspace or project admins and owners can disconnect a project from GitLab at any time in the 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 **one branch at a time**, and that is the branch the project is currently set to (by default the repository's default branch, usually `main`). Merge your changes into the synced branch, or [switch the synced branch](#switch-branches) in your project's GitLab settings. Yes. The branch picker in your project's GitLab repository connection lets you [switch to any branch](#switch-branches) in your repository. You can also [create a new branch](#create-a-new-branch) directly from the picker. Lovable forks from the branch you're currently editing, so switch to your intended starting point (usually `main`) first. Yes. You can connect multiple group namespaces from the same GitLab account or self-managed instance, plus one personal account. 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.