GitHub

​

Overview

GitHub can be connected in two ways:

• API key
• GitHub App installation

Use API key when the connection only needs access to GitHub resources. Use GitHub App installation when the connection also needs to receive webhook events from GitHub.

​

Option 1: Connect With An API Key

API key gives access to the GitHub resources available to that token, but it does not support webhook events from GitHub. Create a GitHub personal access token or other API token with the scopes your workflows need, then create the Mistle connection with:

​

Option 2: Connect With A GitHub App Installation

GitHub App installation gives access through the installed GitHub App and supports webhook events from GitHub.

​

Create The GitHub App

Create a GitHub App in GitHub.com or GHES. Configure these values:

1. GitHub App name (eg. Mistle GitHub App)
2. Homepage URL - Any valid URL for your organization
3. Callback URL - Not necessary. Omit.
4. Webhook secret: create a secret that you will also enter in Mistle
5. Permissions - consider the following permissions in Repository Permissions:

   Permission	Access	Enables
   Actions	Read and write	Trigger runs. Rerun/cancel runs. Inspect workflow runs and artifacts.
   Checks	Read-only	Read check runs.
   Contents	Read and write	Clone/fetch repos. Branch, commit, push. Open PRs from branches. Create releases/tags.
   Issues	Read and write	Create issues. Update issues. Comment on issues.
   Metadata	Read-only	List repos. Read basic repo context.
   Pull requests	Read and write	Open/update PRs. Request reviewers. Comment/review PRs. Merge PRs (repo rules apply).

6. For Subscribe to events, enable the events you want Mistle to take action on. This can be changed later.
7. Private key - Generate and download a PEM private key from GitHub App settings.

​

Connect It In Mistle

Open Integrations in the dashboard, choose the GitHub target, then select GitHub App installation. Enter: installation_id and setup_action are stored automatically after the installation flow completes. You do not enter those manually. app_slug must be the actual GitHub App slug from GitHub, not a display name guess.

​

Copy The URLs From Mistle Into GitHub

After you create the GitHub App connection, open that connection’s detail page in Mistle and copy:

• Webhook callback URL
• Post-installation setup URL

Copy those values directly into your GitHub App settings:

1. Set the GitHub App’s Webhook URL to Mistle’s Webhook callback URL.
2. Set the GitHub App’s Setup URL to Mistle’s Post-installation setup URL.
3. Ensure the webhook is active in GitHub.

Return to Mistle and click Install GitHub App.

​

GitHub Enterprise Server

github-enterprise-server is currently only supported for self-hosted deployments. It is also not enabled by default in the repository’s example target manifest.

​

Official References

• Registering a GitHub App
• Managing private keys for GitHub Apps
• Managing personal access tokens