Prerequisites
- GitHub organization or personal account with admin privileges
Step 1: Register a New GitHub App
- Navigate to your GitHub organization settings (or personal settings)
- Select Developer settings > GitHub Apps > New GitHub App
- Configure the basic app settings:
- GitHub App name: Choose a descriptive name (e.g., “YourCompany MatterAI”)
- Homepage URL: Your company website or internal documentation URL
- Callback URL:
https://matter-backend.example.com/api/v1/auth/github/callback. Replace your domain later. - Webhook URL:
https://matter-backend.example.com/github/webhook. Replace your domain later. - Webhook secret: Generate a secure random string to validate webhook payloads
Keep your webhook secret secure. You’ll need to provide this to your MatterAI instance during configuration.
Step 2: Set Required Permissions
MatterAI requires specific permissions to function properly. Configure the following permission settings:Repository Permissions
Organization Permissions
Account Permissions
Subscribe to Events
Enable the following webhook events:
Step 3: Generate Private Key
- After creating the app, scroll down to the “Private keys” section
- Click Generate a private key
- Save the downloaded
.pemfile securely
The private key is generated only once and cannot be recovered if lost. Store it securely as you would any sensitive credential.
Step 4: Install the GitHub App
- Navigate to your GitHub App’s settings page
- Click on Install App in the sidebar
- Choose the organization or account where you want to install the app
- Select the repositories you want MatterAI to have access to
- You can choose specific repositories or grant access to all repositories