Skip to main content
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. 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:
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, 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 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 and replace their source references with the returned hosted URLs. Use hosted URLs for other media too.
  3. Check the prepared source before committing:
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:
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 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

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.
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.
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.
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.
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.
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.