Creating a GitHub App

Before deploying Shape Docs or contributing to the project, you need to register an app on GitHub. The GitHub App enables two features in Shape Docs:

• Authorizing users with GitHub. Shape Docs uses GitHub to manage access to documentation. Because documentation resides in repositories hosted on GitHub, users only have access to the documentation that resides within the repositories they have access to.
• Commenting on PRs that make changes to OpenAPI specifications. The Shape Docs bot comments on PRs to provide the author and reviewers with links to preview the changes on the web portal.

The following section guides you through creating and configuring the GitHub App. Any settings of the app not mentioned in these settings are irrelevant to Shape Docs. You may also refer to GitHub's official documentation on registering a GitHub App.

Now, let's create and configure a GitHub App.

General settings

Give the app any name, description, and homepage URL that you desire.

Configuring authorization

Specify a callback URL that points to Shape Docs' /api/auth/callback/github endpoint, for example https://example.com/api/auth/callback/github.

Make sure that "Expire user authorization tokens" is enabled.

Configuring webhooks

Specify a webhook URL that points to Shape Docs' /api/hooks/github endpoint, for example https://example.com/api/hooks/github. Make sure that the webhook is activated by checking "Active".

Assign a secret to the webhook. Shape Docs uses this to verify that the webhook is called by GitHub. The secret can be any value. We recommend generating a random string by running openssl rand -hex 32 in your terminal. Store the secret in a secure place, as you'll need to assign it to the GITHUB_WEBHOOK_SECRET environment variable when deploying Shape Docs.

Configuring authorization permissions

Grant the GitHub App following authorization permissions.

Category	Permission	Access	Reason
Repository permissions	Contents	Read-only	Used for finding OpenAPI specifications in repositories.
Repository permissions	Pull requests	Read and write	Enables the Shape Docs bot to comment on pull requests to provide preview links.
Repository permissions	Metadata	Read-only	Required when the "Contents" permission is granted. Enables Shape Docs to search for repositories.

Configuring webhook events

Subscribe to the following webhook events.

Event	Reason
Pull request	Notifies Shape Docs when a PR is opened and new commits are pushed to the PR, enabling the bot to comment on the PR with preview links.

Save the app

Save the GitHub App with the configuration. In summary, your GitHub App should have the following settings.

Setting	Value
Name	Shape Docs
Description	Shape Docs is a web portal that collects OpenAPI documentation and facilitates spec-driven development, built with GitHub-based authorization.
Homepage URL	https://example.com
Callback URL	https://example.com/api/auth/callback/github
Expire user authorization tokens	Yes
Webhook active	Yes
Webhook URL	https://example.com/api/hooks/github
Webhook secret	Generated using openssl rand -hex 32
Repository permissions	Contents set to read-only, Pull requests set to read and write, and Metadata set to read only.

Obtain the app details

Once you have registered the GitHub App, you should take note of the following details:

• App ID.
• Client ID.
• Client secret.
• Private key.

These details are needed when setting the environment variables. The client secret and private key can be generated from the app settings.