oxynote/docs/github.md

GitHub app

Oxynote can watch files in your GitHub repositories. When a watched file changes, the document that relies on it is flagged, so you know it may be out of date.

This needs a GitHub App of your own. Setting one up takes about ten minutes:

1. Create the app on GitHub.
2. Give Oxynote the app's details.
3. Connect your workspace from the app's settings.

The integration is optional. Without it, Oxynote works as usual and only the GitHub hook is unavailable.

Before you start

GitHub must be able to reach your Oxynote server. It tells Oxynote about each installation through a webhook, so OXYNOTE_PUBLIC_URL has to be an address that is reachable from the internet. A localhost or LAN address will not work.

The examples below use https://oxynote.example.com. Replace it with your own public URL.

Creating the app

GitHub can fill in the app form from a link. Open the one that matches where the app should live, after replacing oxynote.example.com with your domain.

For a GitHub organization (replace ORGANIZATION with its name):

https://github.com/organizations/ORGANIZATION/settings/apps/new?name=Oxynote&url=https://oxynote.example.com&setup_url=https://oxynote.example.com/github&webhook_active=true&webhook_url=https://oxynote.example.com/core/api/apps/github/events&public=false&contents=read

For a personal account:

https://github.com/settings/apps/new?name=Oxynote&url=https://oxynote.example.com&setup_url=https://oxynote.example.com/github&webhook_active=true&webhook_url=https://oxynote.example.com/core/api/apps/github/events&public=false&contents=read

The link sets up everything Oxynote needs:

Setting	Value
Setup URL	<OXYNOTE_PUBLIC_URL>/github
Webhook URL	<OXYNOTE_PUBLIC_URL>/core/api/apps/github/events
Repository permissions	Contents: read-only
Visibility	private, so only your account can install it

Oxynote only reads your repositories. It never asks for write access.

Two things are still up to you on the form:

• The name. App names are unique across all of GitHub, so Oxynote is probably taken. Try something like Oxynote Acme.

• The webhook secret. GitHub can't fill this in from a link. Generate one and paste it into the Webhook secret field:

  openssl rand -hex 32
  

  Keep it, because Oxynote needs the same value.

Then click Create GitHub App.

Collecting the app's details

You need four things from the new app's settings page:

What	Where to find it
App ID	the number at the top, next to App ID
Slug	the last part of the app's public link, https://github.com/apps/<slug>
Webhook secret	the value you generated above
Private key	click Generate a private key at the bottom. GitHub downloads a .pem file.

Configuring Oxynote

Docker Compose

Add the details to the oxynote service in your compose file, and mount the private key at /oxynote/github/private-key.pem:

services:
  oxynote:
    environment:
      - OXYNOTE_GITHUB_APP_ID=123456
      - OXYNOTE_GITHUB_APP_SLUG=oxynote-acme
      - OXYNOTE_GITHUB_APP_SIGNATURE_SECRET=<your webhook secret>
    volumes:
      - oxynote_data:/oxynote/data
      - ./github-private-key.pem:/oxynote/github/private-key.pem:ro

Restart the container. The three variables and the key go together. If you set the app ID without the other two variables, or without the key file, the container refuses to boot.

Without Compose

Compose is not required. Any way of running the container works, as long as it sets the three variables and mounts the key at /oxynote/github/private-key.pem. With plain docker run:

docker run -d --name oxynote \
  -p 8080:8080 \
  -e OXYNOTE_GITHUB_APP_ID=123456 \
  -e OXYNOTE_GITHUB_APP_SLUG=oxynote-acme \
  -e OXYNOTE_GITHUB_APP_SIGNATURE_SECRET=<your webhook secret> \
  -v oxynote_data:/oxynote/data \
  -v "$PWD/github-private-key.pem:/oxynote/github/private-key.pem:ro" \
  ghcr.io/oxynote/oxynote:latest

To keep the secret out of your shell history, put the variables in a file and pass --env-file oxynote.env instead of the -e flags.

Connecting your workspace

1. In Oxynote, open Settings, then Apps.
2. Under GitHub, click Activate GitHub Integration. GitHub opens the app's install page.
3. Pick the repositories Oxynote may read, then click Install.

GitHub sends you back to Oxynote, which confirms the connection. That's it.

Install the app as an organization owner. If GitHub turns the install into a request for an owner to approve, Oxynote can't finish the connection yet.

Each workspace connects to one GitHub account. You can disconnect it from the same settings page, or uninstall the app on GitHub.

Watching files

Open a document and add a GitHub Commits hook. Pick a repository, a branch and the files the document describes. When any of those files changes, the hook shows how many of them changed, so you know which documents to review.

Only the repositories you picked during the install show up here. To add more, change the installation's repository access on GitHub.