Creating a GitHub App

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

• Authorizing users with GitHub. Framna 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 Framna 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 Framna 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 Framna 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 Framna 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. Framna 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 Framna 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 Framna Docs bot to comment on pull requests to provide preview links.
Repository permissions	Metadata	Read-only	Required when the "Contents" permission is granted. Enables Framna Docs to search for repositories.

Configuring webhook events

Subscribe to the following webhook events.

Event	Reason
Pull request	Notifies Framna 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	Framna Docs
Description	Framna 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.

Install the app

After registering the app, it must be installed on either your personal account or an organization in order to access private repositories for the account or organization. You may install the app from the "Install App" section of the app details.

Framna Docs supports an app being installed on multiple accounts and organizations and will load repositories for all the organizations an authorized GitHub user is a member of. Note that in order for an app to be installed on organizations that the App Managers aren't part of, the app must be made public. It does not, however, need to be listed on GitHub Marketplace.