Connect to GitHub

⚡️

TL:DR

This guide walks you through the steps of manually connecting your existing Keystatic project to GitHub.

It makes the assumption that you already have:

  • An existing GitHub repository
  • Keystatic working in local mode

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

Local setup

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

Switch to GitHub storage kind

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!

Log in with GitHub

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

Screenshot of the Login with GitHub button

Keystatic setup

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

Screenshot of Keystatic App setup

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

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

Screenshot of GitHub's New App creation UI

Grant repo access

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

Screenshot of successful Keystatic App installation
Screenshot of GitHub custom app authorization UI

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! 🎉

Screenshot of Keystatic's Admin UI for branch dropdown

Environment variables

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 👍


Remote setup

Coming soon 🚧