# Connecting to GitHub

> Link your project to a GitHub repository so you can edit in Typemark or push from your own editor.

Every project starts with a Git repository that Typemark hosts for you. Connect it to GitHub and your docs live in your own repo: edit in Typemark or push from your editor, and both update your site. Any plan can connect, and the project owner sets it up.

## Connect a repository

<Steps>
  <Step title="Install the GitHub App">
    In your project, go to **Settings** > **GitHub** and click **Connect to GitHub**. GitHub asks where to install the Typemark app and which repositories it can access.

    Already connected a GitHub account or organization for another project? It's listed in **Settings** > **GitHub**: click it to go straight to its repositories.
  </Step>
  <Step title="Pick a repository">
    Back in Typemark, choose the repository from the list. If it isn't there, click **Give Typemark access to it on GitHub**, click **Configure** next to the account, add the repository and save: GitHub brings you back to the list. Starting fresh? Create an empty repo on GitHub first, then pick it.
  </Step>
  <Step title="Pick a branch">
    Your site publishes from the repository's default branch unless you choose another one from **Branch**. Type to find it in a repository with many branches. An empty repository has no branches yet, so Typemark uses its default branch. See [Branches](https://docs.typemark.dev/github/branches).
  </Step>
  <Step title="Choose what happens to its content">
    Typemark checks the repository and suggests what to do. See the next section.
  </Step>
  <Step title="Connect">
    Click **Connect** and confirm. Typemark syncs the repository and rebuilds your site.
  </Step>
</Steps>

You can also start a new project from GitHub: choose **Import from GitHub** when you create it, and Typemark takes you straight to the GitHub App install.

## What happens to your content

<Tabs>
  <Tab title="Empty repository">
    Typemark pushes your current docs to the repository's default branch.
  </Tab>
  <Tab title="Repository with typemark.json">
    Typemark recognizes an existing Typemark project on the branch you picked and pulls it. The branch's content replaces your current docs in Typemark.
  </Tab>
  <Tab title="Docs from another platform">
    If the repository has a `docs.json` or `mint.json`, choose **Import from GitHub**. Typemark converts the config to `typemark.json` and publishes your existing pages. See [Migrating your docs](https://docs.typemark.dev/migrating/overview).
  </Tab>
  <Tab title="Other files">
    Choose one:

    - **Push docs to GitHub**: your Typemark content replaces the files on the branch you picked.
    - **Pull from GitHub**: the branch's content replaces your docs in Typemark. It needs a `typemark.json` at the root to build.
  </Tab>
</Tabs>

<Callout type="warning">
  Both choices replace content on one side, and you can't undo them. If the repository holds anything you want to keep, back it up first.
</Callout>

## Requirements

- One repository per project. A repository already connected to another project can't be connected again.
- The repository must be 100 MB or smaller.
- Git submodules aren't supported.
- Typemark uses only the files a docs site needs, so your docs can share a repository with your code. See [Files Typemark doesn't use](https://docs.typemark.dev/github/sync#files-typemark-doesnt-use).

## After connecting

- Saves in the Typemark editor are committed with you as the author and pushed to GitHub.
- Pushes to your deployment branch rebuild your site. See [Sync](https://docs.typemark.dev/github/sync).
- On Pro and Enterprise, pull requests into your deployment branch get a [preview](https://docs.typemark.dev/github/previews).
- Your site publishes from the branch you picked. The owner can change it later in **Settings** > **GitHub**. See [Branches](https://docs.typemark.dev/github/branches).
- **Settings** > **GitHub** shows the connected repository and the branch it publishes from.

## Disconnecting

Click **Disconnect** in **Settings** > **GitHub** and confirm.

- Your project goes back to a repository hosted by Typemark, with all content as of the last sync.
- Your GitHub repository isn't changed or deleted.
- Sync stops in both directions.
- You can connect again later, to the same repository or a different one.
