GitHub mode

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.

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:

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:

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

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:

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

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

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

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

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

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

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

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.

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

To add a redirect URL:

1. Go to the list of "Installed Github Apps"
   • For Users: https://github.com/settings/installations
   • For Organisations: https://github.com/organizations/<org name>/settings/installations
2. Select the app > Choose "App settings"
   • For Users: https://github.com/settings/apps/<app slug>
   • For Organisations: https://github.com/organizations/<org name>/settings/apps/<app slug>
3. Use "Add Callback URL" > Add the additional URL > Save

Now try reloading the authentication page.

Coming soon 🚧

This segment of the Keystatic Mini-Course on YouTube may help understand how to set up the github storage kind: