Creating a GitHub App from a manifest

About GitHub App Manifests

When someone creates a GitHub App from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the GitHub App registration and retrieves the app's webhook secret, private key (PEM file), and GitHub App ID. The person who creates the app from the manifest will own the app and can choose to edit the app's configuration settings, delete it, or transfer it to another person on GitHub.

You can use Probot to get started with GitHub App Manifests or see an example implementation. See "Using Probot to implement the GitHub App Manifest flow" to learn more.

Here are some scenarios where you might use GitHub App Manifests to create preconfigured apps:

• Help new team members come up-to-speed quickly when developing GitHub Apps.
• Allow others to extend a GitHub App using the GitHub APIs without requiring them to configure an app.
• Create GitHub App reference designs to share with the GitHub community.
• Ensure you deploy GitHub Apps to development and production environments using the same configuration.
• Track revisions to a GitHub App configuration.

Implementing the GitHub App Manifest flow

The GitHub App Manifest flow uses a handshaking process similar to the OAuth flow. The flow uses a manifest to register a GitHub App and receives a temporary code used to retrieve the app's private key, webhook secret, and ID.

Follow these steps to implement the GitHub App Manifest flow:

1. You redirect people to GitHub to create a new GitHub App.
2. GitHub redirects people back to your site.
3. You exchange the temporary code to retrieve the app configuration.

1. You redirect people to GitHub to create a new GitHub App

To redirect people to create a new GitHub App, provide a link for them to click that sends a POST request to https://github.com/settings/apps/new for a user account or https://github.com/organizations/ORGANIZATION/settings/apps/new for an organization account, replacing ORGANIZATION with the name of the organization account where the app will be created.

You must include the GitHub App Manifest parameters as a JSON-encoded string in a parameter called manifest. You can also include a state parameter for additional security.

The person creating the app will be redirected to a GitHub page with an input field where they can edit the name of the app you included in the manifest parameter. If you do not include a name in the manifest, they can set their own name for the app in this field.

GitHub App Manifest parameters

Name	Type	Description
name	string	The name of the GitHub App.
url	string	Required. The homepage of your GitHub App.
hook_attributes	object	The configuration of the GitHub App's webhook.
redirect_url	string	The full URL to redirect to after a user initiates the creation of a GitHub App from a manifest.
callback_url	string	A full URL to redirect to after someone authorizes an installation.
description	string	A description of the GitHub App.
public	boolean	Set to true when your GitHub App is available to the public or false when it is only accessible to the owner of the app.
default_events	array	The list of events the GitHub App subscribes to.
default_permissions	object	The set of permissions needed by the GitHub App. The format of the object uses the permission name for the key (for example, issues) and the access type for the value (for example, write).

The hook_attributes object has the following key:

Name	Type	Description
url	string	Required. The URL of the server that will receive the webhook POST requests.
active	boolean	Deliver event details when this hook is triggered, defaults to true.