Skip to main content

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.

When you build with Lovable, your project code is stored and managed inside the Lovable platform. If you want your own copy, plan to collaborate with developers, or move your project elsewhere, you can export and sync your project to GitHub.

​
Why connect Lovable to GitHub

Connecting your Lovable project to GitHub lets you:
  • Back up your code: Store your project safely outside Lovable.
  • Collaborate easily: Invite developers, use pull requests, branches, and code reviews.
  • Sync changes automatically: Edits in Lovable appear in GitHub, and changes pushed to the active GitHub branch sync back into Lovable.
  • Work locally in your IDE: Clone, edit, and commit in your IDE while keeping your project synced.
  • Deploy outside Lovable: Self-host or deploy to alternative platforms, see Deployment, hosting, and ownership options with Lovable Cloud.
  • Test safely: Use branches and pull requests to develop features on a separate branch before merging changes to your live project.
  • Keep code inside your own infrastructure (Enterprise): connect to GitHub Enterprise Cloud with data residency, or to GitHub Enterprise Server running on your own hardware.
You don’t need GitHub 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 and click Download codebase at the bottom of the file tree sidebar (paid plans).

​
How GitHub integration works

Lovable’s GitHub integration has two layers:
  1. A workspace connection
  2. A project repository link

​
Workspace connection

A workspace connection authorizes Lovable to access a GitHub account or organization through the Lovable GitHub app. This grants Lovable permission to create and update repositories in your chosen account or organization. Workspace connections are shared across the workspace and can be reused by multiple projects. A workspace can contain:
  • Multiple GitHub connections
  • Multiple GitHub accounts and organizations
  • Multiple GitHub connection types
This is useful if your team works across personal accounts, client accounts, or multiple organizations.

​
Project repository connection

A project repository connection links one Lovable project to one GitHub repository. When connected:
  • Changes made in Lovable sync to GitHub
  • Changes pushed to the active GitHub branch sync back into Lovable
  • Lovable only edits and syncs one branch at a time

​
GitHub connection types

Lovable supports three GitHub connection types:
  • github.com (available on all plans)
    The standard hosted GitHub platform used by most teams. Lovable manages the GitHub app installation for you.
  • GitHub Enterprise Cloud - Data residency (available on the Enterprise plan)
    GitHub Enterprise Cloud using a *.ghe.com hostname so repository data stays in a specific region. Lovable manages the GitHub app installation for you.
  • GitHub Enterprise Server (available on the Enterprise plan)
    Self-hosted GitHub running on infrastructure your organization controls. With this setup, you create your own copy of the Lovable GitHub app inside your GitHub organization, so credentials remain under your control.
When you add a new connection, you choose which type to set up. All three types support the same two-way sync, branch operations, and pull request creation between Lovable and your GitHub repository.

​
Role-based access for GitHub integration

RoleAllowed action
Workspace owner or admin only
  • Install the Lovable GitHub app on a new account or organization
  • Add a workspace connection
  • Update a workspace connection
  • Reconnect a workspace connection (re-authorize the GitHub app for the workspace connection)
  • Delete a workspace connection
  • Workspace owner or admin
  • Project owner or admin
  • Connect a project to a repository
  • Disconnect a project from a repository
  • Reconnect a project to a repository
  • Workspace editor or higher
  • Project editor or higher
  • View sync status
  • Switch branches
  • Create branches
Any workspace member, including external collaboratorsView the connection in Workspace settings → Git → GitHub (read-only mode)

​
Create a workspace GitHub connection

Workspace admins and owners can create workspace connections from:
  • Workspace settings → Git → GitHub → Add connection
  • Project settings → Git → GitHub → Add connection (if a project has not been connected yet).
To use an existing GitHub installation, click Connect next to the account or organization you want to use. The list shows installations on accounts and organizations you have access to on your GitHub identity.
If someone else installed the Lovable GitHub app on an organization you’re not a member of, you won’t see that installation. Ask them to add you to the GitHub organization, or to set up the Lovable workspace connection themselves.
To set up a new connection, follow the steps for your connection type:
  • github.com
  • GitHub Enterprise Cloud (data residency)
  • GitHub Enterprise Server
github.com is the standard hosted GitHub service used by most teams. Available on all plans. You need to have a GitHub account. You can create one for free at github.com.
1

Add account

Click Add account.
  • On Free, Pro, and Business plans, you’ll go straight to the github.com installation flow.
  • On Enterprise plan, Lovable shows three connection types. Select github.com.
2

Install and authorize the Lovable GitHub app

A GitHub popup opens.
  • Choose the account or organization.
  • Choose All repositories or Only select repositories.
  • Click Install & Authorize.
Lovable automatically detects the installation and adds it as a reusable workspace connection. You can now link projects to repositories under this account or organization.

​
Connect a project to GitHub

When there is an active workspace GitHub connection, workspace or project admins and owners can connect a Lovable project to a GitHub repository.
  • Connecting a project creates a new GitHub repository.
  • Each Lovable project can connect to one repository.
1

Open the project's GitHub settings

You can access project GitHub settings from:
  • Project settings → Git → GitHub
  • The GitHub icon in the top-right corner of the project’s toolbar. Click Connect GitHub.
  • The + (plus) menu in the chat
2

Connect the project

Existing workspace connections appear under Accounts.Click Connect next to the workspace connection where the new repository should be created.Lovable creates a new GitHub repository and starts two-way sync automatically.
Don’t rename, move, or delete your GitHub repository after connecting. Doing so will break the sync, and Lovable won’t be able to update your project.

​
Manage a project’s repository connection

After connecting a project to a GitHub repository, you see the following in the project’s GitHub settings:
  • Repository status as Connected
  • Branch picker with active branch name (GitHub branch synced with Lovable)
  • Clone URLs (HTTPS, SSH, GitHub CLI)
  • Option to View on GitHub (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: <active branch> 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
  • GitHub CLI
You can clone the repository locally and continue working in your preferred IDE.

​
View the repository on GitHub

You can quickly access the synced repository directly in GitHub from:
  • Project settings → Git → GitHub. Use View on GitHub from the repository connection dropdown. This opens GitHub in a new tab.
  • The GitHub icon in the top-right corner of the project’s toolbar. Click the repository name. This opens GitHub in a new tab.

​
Commit attribution

Commits made by Lovable are authored by the Lovable GitHub app identity:
  • lovable-dev[bot] for github.com and GitHub Enterprise Cloud
  • <your-app-name>[bot] for GitHub Enterprise Server
Commits are also co-attributed to the Lovable user who triggered them using GitHub’s noreply email format.

​
Disconnect a project from a GitHub repository

Disconnecting removes the sync relationship between a Lovable project and a GitHub repository. When you disconnect:
  • Sync stops. The two-way connection between Lovable and GitHub ends.
  • Your repository stays on GitHub. 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. There are two ways to disconnect a repository connection.
  • Disconnect from the project GitHub settings
  • Disconnect from the workspace GitHub settings
Workspace or project admins and owners can disconnect from the project’s GitHub settings.
1

Open GitHub settings

You can access project GitHub settings from:
  • Project settings → Git → GitHub
  • The GitHub icon in the top-right corner of the project’s toolbar. Click Configure.
  • The + (plus) menu in the chat
2

Disconnect the project

In the active repository connection, open the dropdown and select Disconnect.
3

Confirm

  • Type the required info
  • Click Disconnect to confirm
If a project needs GitHub 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 GitHub and is no longer linked to Lovable.

​
Delete a workspace GitHub connection

Workspace admins and owners can delete GitHub connections. Deleting a workspace GitHub connection:
  • Removes the connection for all projects
  • Stops syncing for linked projects
  • Does not delete repositories on GitHub
  • Deletes stored credentials
  • For GitHub Enterprise Server, deleting a connection also schedules destruction of the stored GitHub app signing key.
1

Open GitHub settings

Go to Workspace settings → Git → GitHub.
2

Open the connection you want to remove

Select the connection from the list.
3

Review linked projects

Review the list of linked projects carefully before deleting the connection to avoid unintentionally removing GitHub sync.
4

Delete

Under Delete this connection:
  • Click Delete
  • Type the required info
  • Click Delete to confirm the deletion

​
Limitations

The GitHub integration currently does not support:
  • Importing existing GitHub repositories into Lovable. You can only export from Lovable to GitHub.
  • Reconnecting to the same repository after disconnecting. A new repository is created on reconnect.
  • Installing the Lovable GitHub app multiple times on the same account or organization.

​
Troubleshooting

When something goes wrong, Lovable shows a Reconnect prompt in the affected project’s GitHub settings (and in workspace GitHub settings for connection-wide problems).

​
Workspace connection issues

These problems affect the workspace-level GitHub connection itself, so the fix usually applies to every project linked to that connection. A workspace owner or admin can resolve them from the workspace GitHub settings.
The GitHub app installation is currently suspended in your GitHub account or organization.
  1. Open Workspace settings → Git → GitHub.
  2. Open the affected connection and click Reconnect.
  3. Follow the link to your GitHub installation settings and unsuspend the Lovable GitHub app.
When the GitHub app is unsuspended, sync resumes for every project on this connection.
Someone uninstalled the Lovable GitHub app from your GitHub account or organization.
  1. Open Workspace settings → Git → GitHub.
  2. Open the affected connection and click Reconnect.
  3. Reinstall the Lovable GitHub app on the same account or organization when the GitHub popup opens.
All projects on this connection resume syncing automatically.
The Lovable GitHub app is installed but no longer has access to one or more repositories (for example, an admin changed the installation from All repositories to Only select repositories and excluded this one).
  1. Open Workspace settings → Git → GitHub.
  2. Open the connection and click Configure on GitHub.
  3. Under Repository access, either select All repositories or add the missing repository to Only select repositories.
  4. Back in Lovable, click Reconnect to refresh access.
Your project still references a GitHub installation that this workspace no longer has a connection record for (typically after a workspace transfer or cleanup).Click the prompt to reinstall the Lovable GitHub app on that account or organization. Lovable recovers the workspace connection automatically when the install completes.
This affects the GitHub install and authorize popup that opens during workspace connection setup.Your browser probably blocked the GitHub login popup. Allow popups for Lovable and try again.
This applies to data residency and Enterprise Server connections.Add Lovable’s IP ranges (shown in the setup wizard) to GitHub organization → Settings → Security → IP allow list.
Confirm that your GitHub Enterprise Server is reachable from Lovable’s public IP ranges over HTTPS.

​
Project repository issues

These problems affect a single project’s link to its repository. Workspace or project admins and owners can resolve them from the project’s GitHub settings.
The repository was renamed, moved, transferred to another owner, or deleted on GitHub.You can either:
  • Restore the repository on GitHub. Rename it back to its original owner, name, and path, or restore a deleted repository. Sync resumes automatically.
  • Move on with a new repository. Open the project’s GitHub settings, disconnect the project, then connect it again. Lovable creates a new GitHub repository with your current code.
Lovable only syncs one branch at a time, and that is the branch the project is currently set to in its GitHub repository connection settings. By default this is the repository’s default branch (usually main).If you pushed commits to a different branch in GitHub, you have two options:
  • Merge your changes into the synced branch. For example, open a pull 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 GitHub 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 GitHub. 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 GitHub once you’ve moved on.
Your synced branch rejected the push, most often because of branch protection 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-<timestamp> branch instead.Open that branch on GitHub, review the changes, and merge them into your protected branch through your usual review process.

​
FAQ

No. Just connect and authorize. GitHub will safely store your code.You only need to learn GitHub’s features if you want to do more advanced things like branching, pull requests, or CI/CD.
No. On paid plans you can download your code directly from Lovable. Open the Code editor and click Download codebase at the bottom of the file tree sidebar.GitHub is for ongoing two-way sync and collaboration, not just for getting a copy of your code.
  • github.com is the standard hosted GitHub service and is available on all plans.
  • GitHub Enterprise Cloud (data residency) uses a *.ghe.com hostname so your data stays in a specific region. It uses the Lovable-managed GitHub app. Available on the Enterprise plan.
  • GitHub Enterprise Server is GitHub running on your own infrastructure. You register your own copy of the Lovable GitHub app inside your organization. Available on the Enterprise plan.
The Lovable GitHub app requests:
  • Contents (write): Read and write code in your repositories.
  • Metadata (read): Basic repository information.
  • Pull requests (write): Open and update pull requests.
  • Workflows (write): Manage GitHub Actions workflow files.
  • Administration (write): Create new repositories under your account or organization.
The app subscribes to push, pull_request, repository, and delete events to keep Lovable in sync with GitHub.
The GitHub connection breaks. Your project stops syncing, and you are not able to edit it in Lovable.To fix this, restore the repository to its original owner, name, and path. If it was deleted, you can restore it on GitHub.
The GitHub connection breaks. Your project stops syncing, and you are not able to edit it in Lovable.To fix this, revert to the original GitHub user or organization name.
The GitHub connection breaks during the transfer. Lovable shows a warning before you confirm. After the transfer, your repository stays on GitHub but is no longer linked to Lovable.To resume syncing, set up a GitHub connection in the destination workspace and reconnect the project. A new repository is created on reconnect.
You can’t change the linked GitHub account on an existing project. As a workaround:
  1. Disconnect the project from GitHub in the project’s GitHub settings.
  2. Reconnect the project and choose a different installation during setup.
A new repository is created. The original repository stays on GitHub but is no longer linked to Lovable.
Yes. A workspace can have multiple GitHub connections, each pointing to a different personal account or organization, and these can be on github.com, your data residency instance, or your GitHub Enterprise Server. Each Lovable project is then linked to one repository within one of those installations.
Yes. Workspace or project admins and owners can disconnect a project from a GitHub repository at any time in the project’s GitHub settings.Your repository stays on GitHub, but syncing stops. If you reconnect later, a new repository is created.
No. You can only export from Lovable to GitHub, not the other way around.
Yes. The branch picker in your project’s GitHub repository connection lets you switch to any branch in your repository. You can also 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.
Commits made by Lovable are authored by the Lovable GitHub app identity:
  • lovable-dev[bot] for github.com and GitHub Enterprise Cloud
  • <your-app-name>[bot] for GitHub Enterprise Server
Commits are also co-attributed to the Lovable user who triggered them using GitHub’s noreply email format.
Only if Lovable’s public IP ranges can reach your instance. Lovable needs network access to your GitHub Enterprise Server to push code and receive webhook events.
With data residency, repository data and webhook traffic stay within the GitHub region tied to your *.ghe.com hostname. Lovable’s backend connects to that hostname from the IP ranges shown in the setup wizard. If your organization enforces an IP allow list on GitHub, add those ranges to the allow list.