Connect to GitHub

If you need an example repo to follow along, you can clone the Keystatic Manual GitHub Setup Demo repo.

Let's start by connecting your Keystatic local project with GitHub, first.

Assuming your Keystatic project is currently setup with local mode, the storage key in your config looks like this:

storage: {
  kind: 'local',
}

Let's change this to use the github kind instead.

This expects a repo object with keys for the repo owner and name:

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

Make sure the repo owner and name values match an existing GitHub repository. You can store these values in your .env file, or directly inline them in the config — up to you!

Next time you visit a /keystatic route in your browser, you will be prompted to login with GitHub:

Since the project is not connected yet, clicking on the login button should redirect you to a /keystatic/setup page:

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

This will take you to GitHub and prompt you to give a name for your custom GitHub App:

When the custom App is created, you'll need to install it and give it access to your GitHub repo:

After that, you'll be taken back to your local Keystatic Admin UI. But this time, you should see references to your GitHub repo and branches! 🎉

How is Keystatic now connected to our GitHub repo?

The answer lies in the .env file of your project:

# Keystatic
KEYSTATIC_GITHUB_CLIENT_ID=...
KEYSTATIC_GITHUB_CLIENT_SECRET=...
KEYSTATIC_SECRET=...
NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=...

Besides creating a custom GitHub app, the setup process has also generated environment variables used to authenticate users with GitHub, based on their access to the GitHub repo specified in your config's storage.repo settings.

If the user has write access to the repo, they'll be able to access /keystatic routes 👍

Coming soon 🚧