github-mode.mdoc

---
title: GitHub mode
summary: >-
  Walk-through guide of manually connecting your existing Keystatic project to
  GitHub.
---
Keystatic's `github` mode unleashes enhanced collaboration capabilities.

To use it, you'll need your project on an existing GitHub repository. Collaborators will need `write` access to this repository.

---

## Setting up GitHub mode

Start by changing the `storage` option in your Keystatic config to use the `github` kind.

You will need to specifiy a repo `owner` and `name`:

```diff
storage: {
-  kind: 'local',
+  kind: 'github',
+  repo: {
+    owner: REPO_OWNER,
+    name: REPO_NAME
+  }   
}
```


You can also define the `repo` as a string with the `owner/name` format: 

```ts 
storage: {
   kind: 'github',
   repo: `${REPO_OWNER}/${REPO_NAME}`
}
```


### Connecting with GitHub

With `github` mode on, visit the `/keystatic` route. You will be prompted to login with GitHub.

The first time you click this button will initiate the setup process:

{% cloud-image
   src="https://thinkmill-labs.keystatic.net/keystatic-site/images/m89vlce42r9h/create-keystatic-github-app"
   alt="Screenshot of Keystatic App setup"
   height=1480
   width=1468 /%}

If you happen to know the URL of your deployed project and/or the GitHub repo is owned by a GitHub organization, you can fill in those fields.

Otherwise, leave them blank and click on "Create GitHub App".

### Create  a custom GitHub App

The next step will walk you through creating a GitHub App. Choose a name for your app, and proceed.

### Grant repo access

Next, you will need to grant this new GitHub App access to your GitHub repo:

{% cloud-image
   src="https://thinkmill-labs.keystatic.net/keystatic-site/images/oobbqvaxikou/github-app-installation-screen"
   alt="Screenshot of successful Keystatic App installation"
   height=666
   width=892 /%}

{% cloud-image
   src="https://thinkmill-labs.keystatic.net/keystatic-site/images/u7mw0hg9y40m/github-app-permissions"
   alt="Screenshot of GitHub custom app authorization UI"
   height=1902
   width=1348 /%}

Finally, you will be taken back to your local Keystatic Admin UI... running in `github` mode!

{% aside icon="👀" %}
You can tell Keystatic runs in `github` mode by the extra UI around your GitHub repo, like a branch dropdown.
{% /aside %}

### New environment variables

Behind the scenes, some environment variables were generated in a `.env` file on your project:

```bash
# Keystatic
KEYSTATIC_GITHUB_CLIENT_ID=...
KEYSTATIC_GITHUB_CLIENT_SECRET=...
KEYSTATIC_SECRET=...
NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=... # for Next.JS or `PUBLIC_KEYSTATIC_GITHUB_APP_SLUG` for Astro
```

These variables are used to authenticate users with GitHub, based on their access to the GitHub repo in question.

Next time someone with `write` access on the repo visits `/keystatic`, they will be able to login and access the Admin UI.

## Branch prefix

The `branchPrefix` option lets you scope out what GitHub branches Keystatic should interact with:

```diff
storage: {
   kind: 'github',
   repo: 'Thinkmill/keystatic',
+  branchPrefix: 'my-prefix/'
}
```

Keystatic will only list branches starting with `my-prefix/` in the Admin UI, and will only let you create new branches with that prefix.

## Add `redirect_uri`

When you authorize on a server and get the following error from GitHub, you need to modify the GitHub application settings.

{% aside %}

> Be careful!
> The `redirect_uri` is not associated with this application.
> The application might be misconfigured or could be trying to redirect you to a website you weren't expecting.

{% /aside %}

To add a redirect URL:

1. Open your app page by using the value of the `PUBLIC_KEYSTATIC_GITHUB_APP_SLUG` environment variable:
   `https://github.com/apps/<app slug>`
2. Select "App settings"
3. Use "Add Callback URL" > Add the additional URL > Save

Now try reloading the authentication page.

If you don't have the app slug, use the [list of "Installed GitHub Apps"](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify) to find your app.
- For Users: [`https://github.com/settings/installations`](https://github.com/settings/installations)
- For Organisations: `https://github.com/organizations/<org name>/settings/installations`

---

## Deploying Keystatic

Coming soon 🚧

{% aside icon="⚡️" %}
The process of deploying Keystatic can vary based on where you're deploying, but here's the **TL;DR**:

- Copy the Keystatic environment variables over to your deployed environment,
- Make sure the host can run Node.js for Keystatic's API routes.
{% /aside %}

---

## Screencast walk-through

This segment of the [Keystatic Mini-Course on YouTube](https://www.youtube.com/playlist?list=PLHrxuCR-0CcSmkyLcmdV7Ruql8DTm644k) may help understand how to set up the `github` storage kind:

{% embed
   mediaType="video"
   embedCode="<iframe src=\"https://www.youtube.com/embed/BAnfePGzkbg?si=mDDK52Nlhg4v1v9x\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" allowfullscreen></iframe>" /%}