Skip to main content

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-sync/toolkits
    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 skipped with warnings in logs

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

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​