GitHub

• Description
• Limitations
• Setup
  • Create a GitHub App
  • Install the app
  • Configure authentication server

Description

Limitations

This backend requires the creation of a GitHub App, as well as manually configuring an authentication server, in order to support authentication.

Right now, it also stores the pages as .json files, which makes them not easily readable nor editable through GitHub's own UI.

Setup

Create a GitHub App

In order to create a GitHub App, go to https://github.com/settings/apps/new.

Set the name and homepage URL that you want, then under "Identifying and authorizing users" enable "Device Flow":

You can disable the "Webhook" feature, then in "Repository Permissions" select "Contents" as both read and write:

If you only wish to use Cristal with repositories from your own account, you can click "Create GitHub App", otherwise check "Any account" at the bottom.

You should now be redirected to the following page:

Install the app

Using your app's "Public page", you can install it on any repo on which you want to use Cristal. You can find the link to the public page at the bottom left of the app configuration page (see screenshot above).

Simply click the "Install" button and follow the instructions.

Configure authentication server

Cristal provides an authentication server for GitHub through the module authentication-server. You need to input the Client ID of your GitHub App in its configuration file (authentication-server/src/config.ts):

const config = {
  github: {
    DEVICE_LOGIN_URL: "https://github.com/login/device/code",
    DEVICE_VERIFY_URL: "https://github.com/login/oauth/access_token",
    APP_CLIENT_ID: "<Enter your Client ID here>",
  },
};

By default, when running Cristal in dev mode with pnpm, or the Electron build, the server is started on http://localhost:15682. If you start Cristal in another way, you will need to start the server yourself:

nx dev @xwiki/cristal-authentication-server

Make sure that your Cristal configuration for your GitHub repository includes the key authenticationBaseURL and that it points to your running server.