GitHub

​

Overview

GitHub can be connected in two ways:

1. GitHub App installation
   • Create from manifest (recommended): Mistle creates and configures the GitHub App via a manifest
   • Use an existing app: connect a GitHub App you already created in GitHub
2. API key
   • Use this when the connection only needs access to GitHub resources and does not need webhook events

​

Option 1: Connect With A GitHub App Installation

GitHub App installation gives access through the installed GitHub App and supports webhook events from GitHub. Choose one of these setup paths:

1. Create from manifest (recommended): Mistle creates and configures the GitHub App via a manifest.
2. Use an existing app: connect a GitHub App you already created in GitHub.

​

Option 1A: Create From Manifest (Recommended)

1. Open Integrations in the dashboard and choose the GitHub target.
2. Select GitHub App installation.
3. Choose Create from manifest.
4. Choose whether to create the app in a personal account or organization.
5. Review and edit the manifest before creating the app.
6. Submit the manifest to GitHub.
7. Continue the installation in GitHub after the app is created.
8. Return to Mistle to complete the connection.

You can edit the manifest before creating the app. Mistle will use your manifest values for app settings such as the name, description, homepage URL, permissions, and subscribed events. To keep the integration working, Mistle always overrides the webhook and callback settings when it submits the manifest. This ensures GitHub delivers webhook events to Mistle, returns the manifest flow to Mistle after app creation, supports GitHub identity linking, and redirects post-installation setup back to Mistle so the installation can be verified and the connection can be completed. The default manifest includes the GitHub App Email addresses user permission with Read-only access. This is required for GitHub account linking because Mistle reads the authenticated GitHub user’s verified email addresses during linked-account authorization. When creating an organization-owned app, the default manifest also includes the Members and Organization administration organization permissions with Read-only access. Members lets Mistle sync GitHub teams from organizations with accessible repositories. Organization administration lets Mistle sync GitHub App bots from installed apps in those organizations. If you switch the setup to a personal account, Mistle removes those organization-only permissions from the visible manifest before it is submitted.

​

Option 1B: Use An Existing GitHub App

If you already created a GitHub App in GitHub.com or GHES, you can connect it directly in Mistle. Configure these values in GitHub:

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. In Organization Permissions, enable Members with Read-only access when the app should sync GitHub teams for review-request trigger filters.
7. In Organization Permissions, enable Organization administration with Read-only access when the app should sync GitHub App bots from installed apps in organizations with accessible repositories.
8. If this app will be used for GitHub account linking, enable the Email addresses user permission with Read-only access.
9. For Subscribe to events, enable the events you want Mistle to take action on. This can be changed later.
10. Private key - Generate and download a PEM private key from GitHub App settings.

​

Connect The Existing App In Mistle

Open Integrations in the dashboard, choose the GitHub target, then select GitHub App installation. Enter: Client ID is required when this connection will be used for Identity Linking. Installation-only GitHub App usage does not require linked-user authorization. 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.

​

Option 2: 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: To sync GitHub teams for review-request trigger filters, the token must be able to read organization members for each organization whose teams should be listed. To sync GitHub App bots, the token must be able to read organization administration for each organization whose installed apps should be listed.

​

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