Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Connect GitHub from the admin console

Connect GitHub creates a GitHub App for your site with every setting filled in, stores its credentials encrypted, and installs it on your docs repository, so builds, private repositories, GitHub sign-in and the web editor work without environment variables.

Before you begin

  • You are a staff reader (Run your site from the admin console).
  • The site's PUBLIC_URL is its real address: GitHub sends webhooks and sign-ins there.
  • GITHUB_APP_ID is not set. With it, the site uses that app and the console shows it read-only.
  1. Open Admin GitHub, check the app's name (unique on GitHub, at most 34 characters), optionally give the GitHub organization that should own it, and choose Connect GitHub.
  2. Choose Continue to GitHub, then Create GitHub App on GitHub.

    The page sends GitHub an app manifest: the webhook $PUBLIC_URL/webhooks/github (push events), the sign-in callbacks $PUBLIC_URL/auth/github/callback and, when the editor's address is set, $EDITOR_PUBLIC_URL/auth/github/callback, the setup URL $PUBLIC_URL/admin/github/installed, and the permissions in One GitHub App for the site, the editor and builds. The app is private to its owner.

    GitHub sends you back with a one-time code. The site checks that the request carries a signed state from your own session (valid for an hour), exchanges the code for the app's id, client secret, private key and webhook secret, and stores them encrypted.

  3. Install the app on your docs repository when GitHub asks, and choose Install.

    GitHub returns to the setup URL with the installation id. The site asks GitHub, as the app, whether that installation is its own before it stores it.

    Installed on exactly one repository, the app is all the site needs: it finds opend.config.yaml on the default branch, registers the repository with that folder and the branches its site block names, queues the builds, and takes you to the Overview. The next step is then done for you (Set the site up from opend.config.yaml).

  4. On Docs source, pick the repository and choose Use this repository.

    The repository is registered with its installation, and the first build is queued. From now on every push to a release branch or tag builds, and each commit shows an opend/build status.

Results

  • The web service, the worker and the editor all read the stored app from the database, so one connection configures them all, and a new connection applies without a restart.
  • Readers get Sign in with GitHub, matched by a verified email. Turn it off on the Sign-in page if you prefer.
  • Disconnect GitHub removes the stored credentials. Delete the app on GitHub too if you no longer need it.
  • For GitHub Enterprise Server, set GITHUB_WEB_URL and GITHUB_API_URL first.
  • Adding the editor later? Add $EDITOR_PUBLIC_URL/auth/github/callback to the app's callback URLs on GitHub; the console lists the URLs the app needs.

The manual route (create the app yourself and set GITHUB_APP_ID and the other variables) still works; see One GitHub App for the site, the editor and builds.