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:
Keystatic setup
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".
Create a custom GitHub App
This will take you to GitHub and prompt you to give a name for your custom GitHub App:
Grant repo access
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! 🎉
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 🚧