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

# GitHub

> Back up and sync your Macaly project with GitHub

Macaly's GitHub integration connects your project to a private GitHub repository. Back up your code, sync changes both ways, and pick your project back up in a new chat whenever you need to.

<Callout icon="user">
  Available on the [**Pro and Enterprise plans**](/en/welcome/pricing)
</Callout>

## Why connect GitHub

* **Back up your project to a private repo.** Your code lives in a GitHub repository you own.
* **Push updates to GitHub.** Send your latest Macaly version to the repo as a pull request you merge.
* **Pull changes back into your project.** Restore your project from the version stored on GitHub.
* **Import a project from GitHub.** Start a new Macaly project from a repository you pushed earlier.

## Connect GitHub to your project

<Steps>
  <Step title="Open your project settings">
    In your project, click **Settings** in the top bar, then open the **General** tab.
  </Step>

  <Step title="Create the repository">
    Scroll to **GitHub connection** and click **Create on GitHub**. The first time, you'll authorize Macaly to access your GitHub account. Macaly then creates a private repository and syncs your project into it.

    <img src="https://mintcdn.com/macaly-41b1d3e9/mNLiN7clTmvYwZ90/images/integrations_github_create.png?fit=max&auto=format&n=mNLiN7clTmvYwZ90&q=85&s=52b1131022af029916fa54a18c0d8733" alt="Settings General GitHub connection Create on GitHub button" width="2400" height="1600" data-path="images/integrations_github_create.png" />
  </Step>

  <Step title="Your repository is linked">
    The section now shows your repository name with a link to open it on GitHub. From here you can push and pull changes.
  </Step>
</Steps>

## Push and pull changes

Once your repository is linked, the **GitHub connection** section shows two buttons:

* **Push changes** sends your latest Macaly version to GitHub. Macaly opens a pull request titled "Updates from Macaly" that you review and merge on GitHub.
* **Pull changes** replaces your project's files with the version from GitHub. Macaly asks you to confirm first. Your `.env` and `.env.local` files are always kept.

To unlink the repository, click the `X` button next to its name.

## Import a project from GitHub

You can start a new Macaly project from a repository you previously pushed from Macaly.

<Steps>
  <Step title="Turn on the import action">
    Open **Preferences** in your account settings, scroll to **Advanced**, and enable **Import from GitHub**. This shows the action on the home screen.

    <img src="https://mintcdn.com/macaly-41b1d3e9/mNLiN7clTmvYwZ90/images/integrations_github_import.png?fit=max&auto=format&n=mNLiN7clTmvYwZ90&q=85&s=062a4da2b66d8f3e5694b99325da393c" alt="Preferences Advanced Import from GitHub toggle" width="2400" height="1600" data-path="images/integrations_github_import.png" />
  </Step>

  <Step title="Open Import from GitHub">
    On the home screen, open the **+** menu in the prompt bar and choose **Import from GitHub**.
  </Step>

  <Step title="Pick a repository">
    Search for the repository and select it. Macaly creates a new project from it. Use **Configure** to change which repositories Macaly can access, and **Refresh** to reload the list.
  </Step>
</Steps>

<Note>
  Import works with repositories that Macaly created. Importing an external, non-Macaly repository isn't supported.
</Note>

## What gets synced

Your project files, components, pages, styles, assets, and Macaly configuration are included. Environment variables (`.env` files) and cache files are never pushed, and pulling never overwrites your `.env` and `.env.local`.

## Good to know

* **Repositories are always private.** Your code is never made public by Macaly.
* **A free GitHub account works.** You don't need a paid GitHub plan.
* **Pushing opens a pull request** you merge on GitHub. It doesn't change your live site.
* **Pulling replaces your project files** but keeps your `.env` and `.env.local`.