Skip to main content

​
Overview

This guide is for operators running self-hosted Mistle. Use this guide to:
  1. Create and configure a GitHub App for connect + webhook flows.
  2. Add a GitHub provider instance to Mistle runtime config.

​
Prerequisites

Before configuring Mistle, create a new GitHub App dedicated to Mistle and collect:
  1. App ID
  2. App slug
  3. App private key (PEM)
  4. Webhook secret
  5. GitHub base URL:
https://github.com
Helpful GitHub references:

​
Create the GitHub App

Create a new GitHub App from your account or organization settings: 
https://github.com/organizations/<org>/settings/apps/new
For GHES, substitute github.com with your GHES base URL. 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. Set Post installation Setup URL and Webhook URL:
    • For Setup URL, leave Redirect on update as unchecked.
    • For Webhook URL, ensure Active is checked.
https://<control-plane-base-url>/v1/providers/<instance-id>/connect/callback
  1. Webhook secret - Must match webhook_secret in Mistle runtime config.
  2. Permissions - consider the following permissions in Repository Permissions:
    PermissionAccessEnables
    ActionsRead and write- Trigger runs.
    - Rerun/cancel runs.
    - Inspect workflow runs and artifacts.
    ChecksRead-only- Read check runs.
    ContentsRead and write- Clone/fetch repos.
    - Branch, commit, push.
    - Open PRs from branches.
    - Create releases/tags.
    IssuesRead and write- Create issues.
    - Update issues.
    - Comment on issues.
    MetadataRead-only- List repos.
    - Read basic repo context.
    Pull requestsRead and write- Open/update PRs.
    - Request reviewers.
    - Comment/review PRs.
    - Merge PRs (repo rules apply).
  3. For Subscribe to events, enable the events you want Mistle to take action on. This can be changed later.
  4. Private key - Generate and download a PEM private key from GitHub App settings.
  5. App ID and App slug - Copy both into Mistle runtime config (app_id, app_slug).
app_slug must be the actual GitHub App slug (for example from the app URL/settings), not a display-name guess. Mistle uses the GitHub App installation flow and relies on installation context (installation_id) delivered to the Setup URL callback route. It does not require user OAuth token exchange or device-flow-based user authorization for this provider setup, so the Callback URL field can be left unset. If you are testing this locally, use a public tunnel (eg. ngrok) to allow GitHub to reach your control-plane callback/webhook URLs. Configure the GitHub App Setup URL and Webhook URL to the public control-plane endpoint.

​
Configure Mistle Runtime

Add a provider instance under control-plane config: 
[apps.control_plane_api.providers]
internal_auth_token = "replace-me"
credentials_kek = "replace-me"

[[apps.control_plane_api.providers.instances]]
instance_id = "github" # must be unique
provider_id = "github" # must be github
display_name = "GitHub"
enabled = true
webhook_path = "/v1/triggers/github/webhook" # required for webhook-trigger flows

[apps.control_plane_api.providers.instances.config]
app_id = "12345" # positive integer string
app_private_key = "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----"
app_slug = "your-github-app-slug" # must match the GitHub App slug used in install URLs
web_base_url = "https://github.com" # use GitHub.com or your GHES host
# api_base_url = "https://ghe.example.com/api/v3" # optional for GHES
webhook_secret = "replace-me" # required for webhook-trigger flows

​
GitHub.com vs GHES

Behavior is determined by runtime config:
  1. If api_base_url is provided, it is used directly.
  2. If web_base_url is https://github.com, provider uses GitHub.com defaults.
  3. Otherwise, provider derives enterprise-style API base from web_base_url.