Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Connect GitHub: webhooks and the GitHub App

A push webhook tells your OpenD server to build. A GitHub App adds private repositories and commit statuses.

About this task

The quickest way is Connect GitHub in the admin console, which creates and installs the GitHub App, webhook included, without any variables: see Connect GitHub from the admin console. This page is the manual route.

A public repository needs only the webhook. Add the GitHub App when a docs repository is private, or when you want each commit to show whether it published.

  1. Set GITHUB_WEBHOOK_SECRET on the web service to a random string.
  2. Add a webhook to the docs repository: payload URL $PUBLIC_URL/webhooks/github, content type application/json, the same secret, and Just the push event.

    GitHub's ping delivery gets {"status":"pong"}.

  3. Register the repository, with the branches and tags that publish. 
    curl -X POST "$PUBLIC_URL/admin/api/repos" -H "authorization: Bearer $OPEND_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"fullName":"acme/docs","sourceUrl":"https://github.com/acme/docs.git","releaseRefs":["main","v*"],"docsPath":"."}'

    fullName must match the repository name GitHub sends. Pushes to other refs, branch deletions and other events are acknowledged and ignored.

  4. Optional: create a GitHub App for private repositories and commit statuses.
    1. Create the App with repository permissions Contents: Read-only and Commit statuses: Read and write. You can use the App's own webhook, subscribed to push events, instead of per-repository webhooks.

      The web editor needs more permissions; see Run the web editor.

    2. Generate a private key, and set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY on the worker (and the web service, which shares its configuration).
    3. Install the App on the docs repository and note the installation id from the installation's URL.
    4. Register the repository again with "installationId": 12345678.

      Send every field again: registering replaces the repository's settings, and omitted ones go back to their defaults.

Results

  • The webhook checks the X-Hub-Signature-256 signature in constant time and answers 401 to a bad one. Each delivery id is recorded, so a redelivered webhook does nothing. The signature does not cover the delivery id, so a push body is also only acted on once: an old push resent under a new delivery id cannot queue an old commit and roll a release back. To publish an older commit on purpose, request a build of it through the admin API.
  • For a private repository, the worker fetches with an installation token sent as an HTTP header, never in the URL, so it cannot leak into logs. The token is only sent when the sourceUrl is an https URL on github.com, or on the Enterprise host that GITHUB_API_URL names, so register private repositories with their https:// clone URL.
  • With the App installed, every build sets an opend/build commit status: pending, then success (Published 0.1), failure with the first errors, or error when the build could not run.
  • For GitHub Enterprise Server, set GITHUB_API_URL.