GitHub Integration

Connect a GitHub repository to automatically sync your toolkits. When enabled, toolkits will be stored in src/toolkits/[slug].json in your repository, allowing you to version control and track changes to your toolkit configurations.

info

Only general toolkits (without specific owners) are synced to GitHub. User-specific or private toolkits remain in the database only.

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 toolkits
• Permission to create GitHub Apps in your organization

Overview

The GitHub integration uses a GitHub App for authentication, which provides:

• Granular permissions: Only access to specific repositories
• Better security: More secure than Personal Access Tokens
• Webhook support: Automatic bidirectional sync when changes are pushed to GitHub
• Organization-level: Recommended for team collaboration

Step-by-Step Setup Guide

Step 1: Create the Repository

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

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., "Toolkit 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:

   https://your-domain.com/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.

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 toolkit 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

Now, go to your application's admin settings page and:

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 toolkits to GitHub

Step 15: Verify the Setup

Go to your GitHub repository and check that:

• A src/toolkits/ directory was created
• Your toolkits appear as JSON files
• Each toolkit file has a meaningful commit message

How It Works

Automatic Sync (Database → GitHub)

When you create or update a toolkit in your admin panel:

1. The toolkit is saved to the database
2. A background job pushes the change to GitHub
3. A commit is created with the toolkit changes

Webhook Sync (GitHub → Database)

When you push changes directly to GitHub:

1. GitHub sends a webhook notification
2. Your application validates the webhook signature
3. Modified toolkit files are parsed and updated in the database
4. Invalid files are tracked with error details in the toolkit record

Error Tracking

When syncing toolkits from GitHub fails, the system tracks errors in the toolkit record and displays them in the UI with a warning icon. Hovering over the icon shows the specific error details.

Error Types

The following error codes may be displayed:

Error Code	HTTP Code	Description	Resolution
INVALID_JSON	400	The toolkit JSON file contains invalid syntax	Fix JSON syntax errors in the file
VALIDATION_FAILED	400	Required fields (name or slug) are missing	Add missing required fields to the toolkit
MISSING_INTEGRATION	400	Referenced integration doesn't exist in your organization	Add the integration or update the toolkit to use existing integrations
MISSING_TOOL	400	Referenced tool doesn't exist in the integration	Check tool slugs match available tools in the integration
FETCH_FAILED	500	Failed to fetch the file from GitHub	Check GitHub App permissions and repository access

Error Resolution

Errors are automatically cleared when:

• The same toolkit file is successfully synced from GitHub
• You manually edit the toolkit in the admin panel (which triggers a new sync)

To view errors in the toolkit list, look for the warning icon (⚠️) next to the toolkit name. Hover over it to see the error code and message.

Troubleshooting

Connection Test Fails

Error: "Invalid credentials" or "Repository not found"

• Verify your App ID and Installation ID are correct
• Ensure the GitHub App is installed on the repository
• Check that the repository name is in owner/repo format

Error: "Invalid private key"

• Ensure you copied the entire PEM file contents
• Check for no extra whitespace or missing lines
• The key should start with -----BEGIN RSA PRIVATE KEY-----

Webhook Not Working

Toolkits not syncing from GitHub to database

1. Check webhook deliveries in GitHub App settings
2. Look for failed webhook requests (red X)
3. Verify the webhook URL is correct and accessible
4. Check your application logs for webhook processing errors

Webhook signature validation fails

• Ensure the webhook secret matches exactly in both places
• Don't include extra spaces or newlines in the secret

Sync Failures

"Repository is empty" or "Branch not found"

• The repository might not have a default branch yet
• Create an initial commit (e.g., a README file) to initialize the repo
• Ensure you're using the default branch name (usually main or master)

"Permission denied"

• Verify the GitHub App has Contents: Read and write permission
• Check that the app is installed on the correct repository
• Re-install the app if permissions were changed

Toolkit shows error indicator

• Check for a warning icon (⚠️) next to the toolkit name in the toolkit list
• Hover over the icon to see the specific error message
• See the Error Tracking section above for resolution steps
• Fix the issue in GitHub or the admin panel, then push/save to clear the error

Security Best Practices

1. Private Key Management

   • Never commit the private key to version control
   • Store it securely (encrypted environment variables or secrets manager)
   • Rotate keys periodically

2. Webhook Secrets

   • Always use webhook secrets in production
   • Use a cryptographically secure random string
   • Rotate secrets if they're ever exposed

3. Repository Permissions

   • Grant the GitHub App access only to the toolkit repository
   • Use "Only select repositories" instead of "All repositories"
   • Review app permissions regularly

4. Monitor Access

   • Regularly review GitHub App installations
   • Check webhook delivery logs for suspicious activity
   • Audit toolkit changes through Git history

Additional Resources

• GitHub Apps Documentation
• Webhook Events and Payloads
• Best Practices for GitHub Apps