GitHub

Documentation Index

Fetch the complete documentation index at: https://docs.mistle.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

​

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. If this app will be used for GitHub account linking, enable the Email addresses user permission with Read-only access.
7. For Subscribe to events, enable the events you want Mistle to take action on. This can be changed later.
8. 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:

​

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