Skip to content

Create your GitHub App

Register the GitHub App a self-hosted SpecsGraph install uses for sign-in, webhooks and commits: URLs, permissions, events, credentials and installation.

Why you need your own App

SpecsGraph talks to GitHub through a GitHub App. People sign in with it, it receives webhooks when repositories change, and it writes approved spec changes as commits and pull requests. Each self-hosted install needs its own, because GitHub sends an App's webhooks to a single URL. SpecsGraph Cloud, which is coming soon, will use an App run by SpecsGraph instead.

You need owner rights in the GitHub organization that holds your repositories, and the webhook secret you generated during the install (grep GITHUB_APP_WEBHOOK_SECRET .env prints it). The install does not have to be running yet, but the public URL must be final.

Register the App

  1. Open the GitHub App settings

    In your organization on GitHub, go to Settings > Developer settings > GitHub Apps and choose New GitHub App. For an App owned by your personal account, the same path starts from your account settings.

  2. Fill in the basics

    Use the values from the table below. The App name must be unique on GitHub, so include your company, for example SpecsGraph Northwind. Every URL starts with your SPECSGRAPH_PUBLIC_URL.

  3. Set up the webhook

    Keep Active checked, enter the webhook URL and paste the value of GITHUB_APP_WEBHOOK_SECRET as the webhook secret. Leave SSL verification enabled.

  4. Choose permissions, then events

    Set the repository permissions from the next section and leave everything else at No access. The event checkboxes appear once the matching permission is set.

  5. Limit where it can be installed

    Under Where can this GitHub App be installed?, choose Only on this account, then choose Create GitHub App.

FieldValue
GitHub App nameSpecsGraph Northwind
Homepage URLhttps://specsgraph.example.com
Callback URLhttps://specsgraph.example.com/api/auth/github/callback
Webhook URLhttps://specsgraph.example.com/api/github/webhooks
Webhook secretThe value of GITHUB_APP_WEBHOOK_SECRET

Permissions and events

SpecsGraph asks for the smallest set of repository permissions it needs:

Repository permissionAccessWhy
ContentsRead and writeWrite the spec folder and create proposal branches.
Pull requestsRead and writeOpen a pull request for each approved proposal.
MetadataReadList repositories and branches you choose to connect.

GitHub requires Metadata read access for every App and sets it for you. The App subscribes to these webhook events:

EventIn the GitHub formWhy
installationSent to every App, nothing to checkLearn when the App is installed, suspended or uninstalled, so SpecsGraph knows whether it can publish.
installation_repositoriesSent to every App, nothing to checkLearn when repositories are added to or removed from the installation, so the repository picker stays current.
pushCheck PushNotice when a base branch moves, so open spec/ branches can be rebased, and spot commits to the spec folder made outside SpecsGraph.
pull_requestCheck Pull requestFollow the pull requests SpecsGraph opened: merged, closed or reopened. A merge marks the proposal Published.

Credentials and where they go

After you create the App, GitHub opens its settings page. Collect the values there and put each one where the install expects it:

On the App pageGoes to
App ID, near the topGITHUB_APP_ID
Client ID, near the topGITHUB_CLIENT_ID
Generate a new client secret, shown onceGITHUB_CLIENT_SECRET
Generate a private key, downloads a .pem fileThe file at ./secrets/github-app.pem, mounted at /run/secrets/github-app.pem
Webhook secret, which you entered yourselfGITHUB_APP_WEBHOOK_SECRET

Save .env and run docker compose up -d to apply the values. Configuration covers how to store the key file.

Note

Check the first webhook

GitHub sends a ping to the webhook URL when the App is created. Under Advanced > Recent Deliveries in the App settings you can see whether it arrived. If the install was not running yet, choose Redeliver once it is.

Install the App on your repositories

In the App settings, open Install App and choose Install next to your organization. Pick Only select repositories and choose the repositories that should hold specs. You can add more later from the same page.

Then connect the workspace to the installation and each project to its repository from inside SpecsGraph, as described in Connect GitHub.

Rotate credentials

  • Private key. Generate a new key, replace the file, run docker compose up -d --force-recreate, then delete the old key in GitHub.
  • Client secret. Generate a new secret, update GITHUB_CLIENT_SECRET, apply it, then delete the old secret in GitHub.
  • Webhook secret. Generate a value with openssl rand -hex 20, then update GitHub and GITHUB_APP_WEBHOOK_SECRET together. Redeliver any deliveries that failed in between.

Next steps