Guide
Lovable GitHub Sync: How It Works Day to Day
Lovable GitHub sync connects your project to a repository and keeps the code there in step with the editor. It is available on every plan, unlike the ZIP download, which needs a paid plan. Day to day it is two-way: prompts in Lovable produce commits, and commits you push can show up back in the project. Most breakages come from the same few causes: edits to files the editor also owns, renamed branches, build errors and missing environment variables.
What GitHub sync actually gives you
A Lovable project is a normal front-end codebase. It is React and TypeScript, styled with Tailwind CSS and shadcn/ui components. Syncing to GitHub puts that codebase in a repository you control.
Two things follow from that. First, you get a full history: every change the editor makes lands as a commit, so you can read diffs and roll back. Second, you get an exit route. Any static host, any CI pipeline, any developer with a laptop can clone the repo and run it.
The shape of the code depends on when the project was created. Apps created from 13 May 2026 use TanStack Start with file-based routes in src/routes and a head() per route. Older apps are React plus Vite, with pages in src/pages and routes declared in src/App.tsx. Open those paths first when you want to find your way around a fresh clone.
GitHub sync works on every plan. The "Download codebase" ZIP needs a paid plan. If you are only choosing between the two, our export guide compares them side by side.
Connecting the repository
Connecting is a one-time setup inside Lovable. You authorise GitHub, pick or create a repository, and Lovable pushes the current state of the project as the first commit.
After that, treat the repository as the source of truth for code and Lovable as the source of truth for the live preview. They should agree. When they drift, something in the list further down is usually the reason.
- Authorise GitHub from the Lovable project. Grant access to the account or organisation that should own the repo, not a personal account you plan to leave.
- Create or select the repository. A dedicated repo per project is easier to reason about than a monorepo folder.
- Wait for the first push to finish. Check that
package.json,src/andpublic/are all there before you do anything else. - Clone it locally and prove it builds. Run
npm installand thennpm run buildon Node 22. You should get adist/folder. - Write down the default branch name. This is the branch Lovable watches. Changing it later is the single most common way to break the sync.
The day-to-day loop
In normal use you prompt in Lovable, the editor edits files, and those edits are committed to the connected branch. You can watch the commits appear in GitHub within moments of the preview updating.
Going the other way, you can push changes from your machine or merge a pull request, and the project picks them up. That is what makes the sync genuinely two-way rather than a one-time export.
The practical rule is to avoid editing the same files from both sides at the same time. Pick a lane for each change: layout, copy and components through the editor; build config, dependency pins and CI through Git. When you do need to work in Git on something the editor also touches, finish and merge first, then go back to prompting.
Branches are useful here. Do larger refactors on a branch, open a pull request, review the diff, then merge into the branch Lovable watches. The editor keeps working on the default branch while you do.
- Small prompt edits: do them in Lovable and let the commit flow to GitHub.
- Dependency and config changes: do them in Git, where you can see the lockfile diff.
- Risky refactors: branch, pull request, merge. Do not hand-edit the default branch while prompting.
- Secrets and keys: never commit them. Variables prefixed
VITE_are baked into the build and visible in the browser.
The mistakes that break the sync
Most broken syncs are not mysterious. They come from a handful of repeatable mistakes.
The first is renaming or deleting the branch Lovable is connected to. The editor keeps pushing to a branch that no longer matches your workflow, and your merges land somewhere it never reads.
The second is force-pushing or rewriting history. A rebase that rewrites commits the editor already made leaves the two sides with different histories. Prefer merge commits on the connected branch.
The third is editing generated or editor-owned files by hand and then prompting over the top. The editor rewrites the file, your change disappears, and it looks like the sync dropped work. It did not; the edit was simply overwritten.
The fourth is breaking the build. If npm run build fails in the repo, the preview and any external host both fail. Run the build locally before you merge anything. The fifth is environment variables: VITE_ values are read at build time, so a host that does not have them set produces a build that silently misses configuration.
- Renamed or deleted branch — reconnect the project to the branch you actually use.
- Force-push or rebase on the connected branch — rewrite history on side branches only.
- Hand edits to files the editor owns — they get overwritten on the next prompt.
- A failing
npm run build— fix it in Git before expecting the editor to recover. - Missing
VITE_variables on the host — the build succeeds but the feature does not work. - Two people prompting and pushing at once — agree who owns the default branch that day.
Recovering when the two sides disagree
Start by deciding which side is correct. Usually the repository is, because it has the history. Open the commit list in GitHub and find the last state you trust.
If the editor has lost a change you made in Git, check whether a later Lovable commit overwrote the same file. The diff will show it plainly. Re-apply the change, then stop prompting on that file.
If Git has a state you do not want, revert the commit rather than force-pushing over it. A revert is itself a commit, so both sides end up with the same history.
If the connection itself looks wrong — commits stop arriving, or they arrive on a branch nobody reads — reconnect the project to the correct repository and branch. Lovable's own documentation at docs.lovable.dev covers the current reconnection flow and any limits per plan; check there rather than guessing from an older screenshot.
Using the repo outside Lovable
Once the code is in GitHub you can build and host it anywhere. The output of npm run build is static files in dist/, so Netlify, Vercel and Cloudflare Pages all work with no special setup. Point the host at the repo, set the build command, set your VITE_ variables, and deploy on push.
One thing does not travel. Lovable's crawler prerendering is part of Lovable hosting. An older React plus Vite app hosted elsewhere is rendered in the browser, so crawlers that do not execute JavaScript see an empty app shell. Apps created from 13 May 2026 use TanStack Start and are server-rendered, so they serve full HTML wherever they run. Our hosting guide and our SEO guide go into what that means for rankings.
A connected repository is also the cleanest input to a WordPress migration. Our converter reads either the Lovable ZIP or a GitHub repository and produces a WordPress block theme: templates, header and footer template parts, one pattern per page, a theme.json with your palette and fonts, and your images copied in. Conversion, review and the theme download are free, and the review screen shows the converted site next to the original inside WordPress Playground. Pointing it at the repo means you never have to remember which ZIP was the latest one.
Before you migrate, read what converts and what does not. Custom React state, event handlers, Supabase, authentication, dashboards and API calls are application logic, not markup, and they do not become blocks.
FAQ
Is Lovable GitHub sync available on the free plan?
Yes. GitHub sync works on every Lovable plan. The "Download codebase" ZIP is the feature that requires a paid plan, so syncing to a repository is the free way to get your code out.
Is the sync one-way or two-way?
It is two-way. Changes you make by prompting in Lovable are committed to the connected repository, and changes you push to that repository can appear back in the project. The usual advice is to avoid editing the same files from both sides at once.
Why did my manual code change disappear after I prompted in Lovable?
The editor rewrote the same file and your edit was overwritten. The change is still visible in the GitHub commit history, so you can re-apply it. For files the editor touches often, make the change through a prompt instead of by hand.
Can I rename the branch that Lovable is connected to?
Renaming or deleting the connected branch is one of the most common ways to break the sync, because commits keep going to a branch you no longer use. If you must rename it, reconnect the project afterwards. Check docs.lovable.dev for the current reconnection steps.
Can IQDesk convert a Lovable site straight from GitHub?
Yes. The IQDesk converter accepts either the Lovable ZIP or a GitHub repository and produces a WordPress block theme. Conversion, review and the theme download are free, and you can compare the result with the original in WordPress Playground before you download.