# How to sync your project to GitHub

> Two-way sync with a repo you own: every build is a commit, every push flows back. Plus what "diverged" means and why it quietly stops your branch updating.

Canonical: https://vibely.sh/guides/how-to-sync-your-project-to-github
Last updated: 2026-09-19

Published 2026-09-19 · Build workflow · 5 min read

## Reference documentation

- [Git sync](https://docs.vibely.sh/integrations/git-sync)
- [Publish](https://docs.vibely.sh/features/deploy/publish)

Link a project to a [GitHub](https://vibely.sh/features/code) repository and the code stops living only in Vibely. Every build pushes a commit; every push you make to the linked branch flows back into the project. Work in your IDE, review in pull requests, deploy it yourself — or keep building in chat and let the repo follow along.

**GitHub is the only supported provider.** GitLab and Bitbucket are not supported.

## Connect a repository

1. Project menu → **Connect GitHub**, or **Settings → Git**. You install a GitHub App on the account or organisation that owns the repo and choose which repositories it can see.
2. Create a new repository or link one you already own, then pick the branch to sync. The branch can be changed later.

The App asks for Contents (read & write) to push commits and read the tree, Metadata (read) because GitHub requires it, Pull requests (read & write) to open the PR a diverged project needs, Workflows (read & write) so changes under `.github/workflows` can be pushed, and Administration (read & write) only so Vibely can create a repository for you. Granting access to existing repositories only is perfectly fine if you create the repo yourself.

## What sync actually does

| Direction | Trigger | Result |
| --- | --- | --- |
| Vibely → GitHub | Each build that changes files | One commit on the linked branch, co-authored by the GitHub account that connected |
| GitHub → Vibely | A push to the linked branch | The changed files land in the project — deletions and renames included |

Inbound pushes arrive over a webhook, so the project updates without you opening it. The first import reads the whole tree; after that only the diff moves.

## Read this before it happens: "diverged"

Vibely **never force-pushes**. If the linked branch has moved ahead on GitHub and Vibely's commit would not fast-forward, the commit is parked on a branch called `vibely-sync`, the project is marked **diverged**, and you are told to open a pull request from `vibely-sync` into your branch.

Nothing is lost and nothing is overwritten. But further builds keep landing on `vibely-sync`, not on your branch — so a diverged project nobody merges quietly stops updating the branch you are watching. If your repo looks stale, check for that state first.

## The code is genuinely yours

A synced repo is a normal project tree. Clone it, `bun install`, `bun dev` — it runs locally with no Vibely involved. That is also the first step if you ever want to [move the app off Vibely entirely](https://vibely.sh/guides/how-to-move-your-app-off-vibely).

## Related

- [How to use plan mode](https://vibely.sh/guides/how-to-use-plan-mode) - previous guide
- [Why is my preview blank?](https://vibely.sh/guides/why-is-my-preview-blank) - next guide
- [Build workflow guides](https://vibely.sh/guides/category/workflow)
