> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync a project with a repository

> Link a project to a GitHub repository and keep both sides up to date.

A project linked to a GitHub repository stays in sync both ways. What you build in Polymet is pushed to GitHub, and what developers push to GitHub comes back into Polymet.

Linking a project to a new repository needs a paid plan. Importing a repository you already have works on every plan, and so does a link you made while on a paid plan after you downgrade.

You need a connected GitHub account first. See [Connect GitHub](https://docs.polymet.ai/github/connect.md).

## Link a project to a new repository

1. Open the project's settings on the **GitHub** tab and click **Link Project**.
2. In **Link Project to GitHub**, pick the account under **Owner** and type a **Repository name**.
3. Click **Link**. Polymet creates a new private repository and pushes every branch of the project to it.
4. You see **Project linked to GitHub**. Click **View on GitHub** to open the repository.

To link a repository that already exists, import it instead: [Import from GitHub or a ZIP](https://docs.polymet.ai/canvas/import-code.md). One repository links to one project.

## How the sync works

| When | What happens |
| - | - |
| You or the Polymet Agent save a change in Polymet | It is pushed to the GitHub branch with the same name |
| Someone pushes to GitHub | The change arrives on the Polymet branch with the same name, on its own |
| Someone creates or deletes a branch on GitHub | The branch is added to or removed from the project. A branch with Polymet work GitHub does not have yet is kept |
| Both sides changed and cannot be combined | GitHub's version wins. Every Polymet change on that branch that GitHub does not have is dropped |
| Someone force-pushes on GitHub | The Polymet branch is reset to GitHub's version |

New files pushed from GitHub show in the project's files. They get a node on the canvas once the agent uses them in a page or component.

## Sync from GitHub by hand

If a change from GitHub has not arrived, click **Sync from GitHub** (the arrows button next to the repository name). It syncs the branch you are on.

| You see | It means |
| - | - |
| **Synced with GitHub** | Changes came in |
| **Already up to date** | Nothing new on GitHub |
| **"branch" is busy — sync again once it finishes** | A generation or merge is running on that branch |
| **"branch" isn't on GitHub yet — your next change pushes it** | The branch has not been pushed yet |

## Branches

* Every project branch has a GitHub branch of the same name. A branch you start in Polymet is pushed right away, and a name the repository already uses is refused.
* When you delete a branch, tick **Also delete** *branch* **on** *owner/repo* to remove it from GitHub too. It is off by default. A branch left on GitHub comes back into Polymet with its next push.

## When GitHub refuses a push

Your change is always kept in Polymet. If GitHub refuses it because of a repository rule, secret scanning or a file over GitHub's size limit, you see **Saved in Polymet**. GitHub refuses every later push of that branch too until you remove the secret or the file. A push to a protected branch is refused without a message.

## Unlink a project

1. On the **GitHub** tab, open the menu next to the repository and click **Unlink**.
2. In **Unlink from GitHub?**, click **Unlink**.

The repository is not deleted. Changes stop syncing in both directions.

## Related

* [Connect GitHub](https://docs.polymet.ai/github/connect.md) — connect your account and install the Polymet app
* [Import from GitHub or a ZIP](https://docs.polymet.ai/canvas/import-code.md) — start a project from an existing repository
* [Branches](https://docs.polymet.ai/team/branches.md) — start, compare and merge branches
* [Export your code](https://docs.polymet.ai/publish/export-code.md) — download a ZIP instead


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.