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

# GitHub

> Create a repository, copy your site into an existing repo, or connect a publication in a subfolder.

Connect GitHub to edit your publication locally and publish changes when you push.
Your site uses one repository, one branch, and one publication folder. Manage them
in [**Settings → Git**](https://www.lettercamp.com/settings/git).

Lettercamp creates a managed repository when you create a hosted site. You can
keep using the web editor without connecting your own GitHub account. Connect your
own repository when you want to manage the files in your personal account or
organization.

## Connect your GitHub account

You must be the site owner to change a site's Git connection. For
an existing repository, you also need GitHub administrator access. Both public
and private repositories are supported.

1. Open your site and go to **Settings → Git**.
2. Save or discard any pending editor changes.
3. Click **Change repository**, then **Connect GitHub** if prompted.
4. Authorize Lettercamp to access your GitHub account.
5. Click **Manage GitHub access** to install the Lettercamp GitHub App on your
   personal account or organization. Choose **Only select repositories** to grant
   access to the repositories you want to connect.
6. Return to Lettercamp and click **Refresh accounts**.

Your organization may require an owner to approve the App installation. Signing
in to Lettercamp with GitHub does not replace this connection step. You can also
connect GitHub if you signed in with email or Google.

## Create a new repository

Use this option to copy your current site's saved files into your own account.

1. Choose your **Account or organization**.
2. Select **New repository**.
3. Enter a **Repository name** and choose **Visibility**. Private is the default.
4. Leave **Folder** empty to use the repository root, or enter a folder name.
5. Click **Create repository and connect**.

Lettercamp copies your saved files into a new commit. Git history, other branches,
and tags are not transferred. A public repository makes its saved source files
visible to everyone, including pages marked as drafts.

If GitHub requires you to grant the App access to the new repository, click
**Manage GitHub access**, add the repository, and refresh. Then select it under
**Existing repository** to finish connecting.

## Copy into an existing repository

Use this option to add your publication alongside another project, such as a
website or application.

1. Choose your **Account or organization** and select **Existing repository**.
2. Choose the destination **Repository**.
3. Enter a **Folder**. Lettercamp suggests `blog`.
4. Under **Content**, select **Copy this site into an empty folder**.
5. Click **Copy site and connect**.

The destination folder must be new or empty. Lettercamp preserves files outside
that folder and refuses to overwrite files already inside it.

For example, choosing `blog` creates this layout:

```text theme={null}
my-project/
├── src/
└── blog/
    ├── settings.json
    ├── pages/
    └── components/
```

You can connect separate sites to separate folders in the same repository.
Their folders must not overlap on the same branch.

## Use an existing publication

If you already have a Lettercamp publication in GitHub, connect it directly.

1. Choose your **Account or organization** and select **Existing repository**.
2. Choose the **Repository** containing your publication.
3. Set **Folder** to the directory containing `settings.json` and `pages/`.
   Leave it empty if those files are at the repository root.
4. Under **Content**, select **Use the publication already in this folder**.
5. Click **Connect repository**.

Select the publication folder, such as `blog`, rather than `blog/pages`.
The selected folder should contain all of the publication's local files and
components. Imports from elsewhere in a monorepo are not supported.

To create the files locally first, follow the [quickstart](https://www.lettercamp.com/docs/quickstart.md), prepare
the assets as described below, commit the publication to GitHub, then connect
its repository and folder here.

### Prepare local assets for Cloud

For a new publication, you can use the optional
[`--remote-assets` setup](https://www.lettercamp.com/docs/cli/new#optional-start-with-remote-assets) to start with
hosted starter images and fonts. You only need to prepare local assets you add later.

GitHub publishing builds your committed source. It does not run the CLI's
automatic local image uploads. For a project created with local starter assets:

1. Set `design.typography.localFonts` to `false` in `settings.json`.
2. [Upload local images and custom fonts](https://www.lettercamp.com/docs/cli/upload.md) and replace their source
   references with the returned hosted URLs. Use hosted URLs for other media too.
3. Check the prepared source before committing:

   ```bash theme={null}
   npx lettercamp build --site https://example.com --remote-assets-only
   ```

Replace the example URL with your publication's address. A normal standalone
build supports local files, so use `--remote-assets-only` to check Cloud's
requirements. `public/` is not served by Cloud. Sites created in the Cloud
dashboard already use hosted starter assets.

## Choose a branch

Lettercamp uses the repository's default branch when you connect. To use another
existing branch, expand **Advanced** and enter its name in **Branch**.

After connecting, Lettercamp keeps using that selected branch even if you change
the repository's default branch in GitHub.

## Edit and publish

Once connected, saved web editor changes are committed to the selected repository,
branch, and folder. You can also clone the repository, edit locally, and push your
changes. Pushes that change the publication folder trigger a build. Changes outside
that folder do not rebuild the site, and pages marked as drafts stay unpublished.

For a CLI-created publication in `blog/`, install its dependencies and preview
from that folder after cloning:

```bash theme={null}
cd my-project/blog
npm install
npm run dev
```

If the publication was created in Cloud and has no `package.json`, run
`npx lettercamp@latest dev` from its folder instead.

See the [CLI guide](https://www.lettercamp.com/docs/cli.md) for installation and preview options.

When you change a Git connection, Lettercamp builds the destination before
switching. Your current site stays live. If the build fails, your previous
connection remains active. Your site address and custom domains stay the same.
Uploaded images keep their existing HTTPS URLs; copying the repository does not
move those images into Git.

After a successful switch, future edits go to the new location. The previous
repository is retained but is no longer synchronized with the site.

## Repository access

The GitHub App needs access to your selected repository to read files and commit
editor changes. Review the permissions GitHub displays during installation.
GitHub grants access to a whole repository; the **Folder** setting controls which
part Lettercamp uses for your publication.

Use **Manage GitHub access** to update the App's repository access. Connecting a
repository allows members of your site to edit the publication
through Lettercamp.

## Troubleshooting

> [accordion] My account or repository does not appear
>
> Confirm that the Lettercamp GitHub App is installed on the correct personal
> account or organization and has access to the repository. You must administer
> the repository, and it must not be archived. If your organization requires
> approval, wait for an owner to approve the installation. Then click
> **Refresh accounts**.

> [accordion] The destination folder already contains files
>
> Choose a new or empty folder to copy your site. If the folder already contains
> a Lettercamp publication, choose **Use the publication already in this folder**
> instead. Lettercamp does not merge the two publications.

> [accordion] The publication cannot be found or built
>
> Check that the selected branch exists and the selected folder contains
> `settings.json`. Review the connection error in **Settings → Git**. You can
> also run `npx lettercamp build --site https://example.com` from the publication
> folder to check it locally. Your previous connection stays active if the new
> source fails to build.

> [accordion] GitHub blocks changes from the web editor
>
> Check the App's write access and your repository's branch protection rules.
> Lettercamp does not bypass those rules. If your branch requires pull requests,
> make your edits in GitHub or locally and open a pull request in GitHub. Merging
> into the connected branch triggers publishing.

> [accordion] A push does not update the site
>
> Check the repository, branch, and folder shown in **Settings → Git**, and
> confirm the App still has repository access. Changes outside the publication
> folder do not trigger a build. Check **Activity** for a pending or failed
> publish. If a build fails, the last successful version stays live.

> [accordion] GitHub connections are not available
>
> GitHub connections apply to sites hosted by Lettercamp. Local development
> sites use their content folder. If connections are unavailable for your
> hosted site, keep using its current repository and contact
> [support@lettercamp.com](mailto:support@lettercamp.com).


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