Skip to main content

Set Up the GitHub Integration

This guide takes you through creating a GitHub App and connecting it so your organization's configuration syncs to a repository.

For what gets synced and how sync behaves, see GitHub Integration.

Prerequisites​

Before setting up GitHub integration, ensure you have:

  • A GitHub organization account with admin permissions
  • A repository (public or private) where you want to sync your configuration
  • Permission to create GitHub Apps in your organization

Step-by-Step Setup Guide​

Step 1: Create the Repository​

Create a new repository on GitHub where you want to sync your configuration. Note the repository name in owner/repo format (e.g., acme-corp/mcp-config).

Step 2: Navigate to GitHub Apps Settings​

Go to your organization's GitHub Apps settings page:

https://github.com/organizations/YOUR_ORG/settings/apps

Replace YOUR_ORG with your organization name.

Step 3: Create a New GitHub App​

Click the "New GitHub App" button.

Step 4: Configure Basic Information​

  • GitHub App name: Give your app a descriptive name (e.g., "Willow Sync")
  • Homepage URL: Add your organization's website or app URL
  • Description: Optional, but helpful for team members

Step 5: Configure Webhook Settings​

Scroll down to the "Webhook" section and configure:

  1. Ensure "Active" is checked

  2. In the "Webhook URL" field, enter your webhook endpoint:

    • For SaaS deployments: https://app.withwillow.ai/api/github/webhook
    • For On-Premise deployments: {your-app-url}/api/github/webhook
    tip

    You can copy this URL from the GitHub Integration settings page in your admin panel.

  3. (Recommended) Add a Webhook Secret for security:

    • Generate a secure random string (e.g., using openssl rand -hex 32)
    • Save this secret - you'll need to enter it in your admin settings
    • This ensures webhook requests are authentic
Security Best Practice

Always use a webhook secret in production environments to prevent unauthorized webhook calls.

Step 6: Set Repository Permissions​

Scroll to "Repository permissions" and configure:

  • Contents: Set to Read and write

This allows the app to read and create files in your repository.

  • Pull requests: Set to Read and write

This allows the app open pull requests.

Step 7: Subscribe to Events​

Under "Subscribe to events", check:

  • Push: This enables automatic sync when changes are pushed to GitHub

Step 8: Create the GitHub App​

Click "Create GitHub App" at the bottom of the page.

Step 9: Generate Private Key​

After creation, you'll see a banner with "Generate a private key". Click it to download a PEM file.

caution

Store this private key securely. You'll need to paste its contents into your admin settings. Never commit this key to version control.

Step 10: Extract the Private Key​

Open a terminal and navigate to where the PEM file was downloaded:

cat your-app-name.2024-01-01.private-key.pem

Copy the entire output, including the BEGIN and END lines.

Step 11: Copy the App ID​

On the GitHub App settings page, copy the "App ID" (displayed near the top of the page).

Step 12: Install the GitHub App​

  1. On the left sidebar, click "Install App"
  2. Click "Install" next to your organization
  3. Select "Only select repositories"
  4. Choose your configuration repository
  5. Click "Install"

Step 13: Get the Installation ID​

After installation, check your browser's URL. It should look like:

github.com/organizations/YOUR_ORG/settings/installations/12345678

The digits at the end (12345678) are your Installation ID. Copy this number.

Step 14: Configure in Admin Settings​

Go to settings -> GitHub Integration:

  1. Click "Connect GitHub"
  2. Fill in the form with:
    • Repository Name: owner/repo format
    • App ID: From Step 11
    • Installation ID: From Step 13
    • Private Key: Contents from Step 10
    • Webhook Secret: The secret you created in Step 5 (if any)
  3. Click "Connect"

The system will automatically:

  • Save your settings
  • Test the connection
  • Sync all existing entities to GitHub

Step 15: Verify the Setup​

Go to your GitHub repository and check that:

  • Directories were created (toolkits/, commands/, skills/, etc.)
  • Your entities appear as files in their respective directories
  • Each file has a meaningful commit message

What to do next​

On this page