GitHub Integration

Connect a GitHub repository to automatically sync your organization's configuration. When enabled, your toolkits, skills, commands, MCP servers, and MCP clients will be stored as code in your repository, allowing you to version control and track changes.

info

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

What Gets Synced

The GitHub integration syncs the following entity types:

Entity Type	Directory	Format	Notes
Toolkits	src/toolkits/	JSON files	One file per toolkit
Commands	src/commands/	JSON files	One file per command
MCP Servers	src/mcp-servers/	JSON files	Auth credentials excluded for security
MCP Clients	src/mcp-clients/	JSON files	One file per client
Skills	src/skills/	Directory per skill	Contains SKILL.md, scripts, references

Sensitive Data

Authentication settings for MCP servers (API keys, secrets, OAuth credentials) are never synced to GitHub for security reasons. Only the configuration structure is synced.

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

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 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., "Webrix 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://{your-webrix-org}.mcp-s.com/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 (src/toolkits/, src/commands/, src/skills/, etc.)
• Your entities appear as files in their respective directories
• Each file has a meaningful commit message

How It Works

Automatic Sync (Database → GitHub)

When you create or update any entity in your admin panel:

1. The entity is saved to the database
2. A background job pushes the change to GitHub
3. A commit is created with descriptive message

Supported operations:

• Toolkits: Synced as src/toolkits/{slug}.json
• Commands: Synced as src/commands/{slug}.json
• Skills: Synced as directory src/skills/{slug}/ with SKILL.md, scripts, references, and assets
• MCP Servers: Synced as src/mcp-servers/{slug}.json (auth credentials excluded)
• MCP Clients: Synced as src/mcp-clients/{slug}.json

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 files are detected and classified by type
4. Files are parsed and entities are updated in the database
5. Invalid files are tracked with error details in the entity record

File detection:

• JSON files (*.json) in respective directories are parsed directly
• Skill directories are reconstructed from all files in src/skills/{slug}/

Error Tracking

When syncing entities from GitHub fails, the system tracks errors in the entity's git_integration field 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 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 entity
EMPTY_DIRECTORY	400	Skill directory is empty or missing SKILL.md	Add SKILL.md file to the skill directory
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 entity file is successfully synced from GitHub
• You manually edit the entity in the admin panel (which triggers a new sync)

To view errors, look for the warning icon (⚠️) next to the entity name in the list view. 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

Entities 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
5. Ensure files are in the correct directories (src/toolkits/, src/commands/, src/skills/, etc.)

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

Entity shows error indicator

• Check for a warning icon (⚠️) next to the entity name in the list view
• 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

"Sync successfully 0 entities" or nothing syncing

If the sync completes without errors but 0 entities are synced to GitHub, check:

1. Branch Protection Rules

   • GitHub branch protection rules may be blocking commits
   • Check your repository's branch protection settings
   • Ensure the GitHub App is allowed to bypass protections, or disable protections temporarily
   • Go to: Settings → Branches → Branch protection rules

2. Network/Firewall Issues

   • Your server may be unable to reach GitHub's API
   • Check outbound network connectivity to api.github.com
   • Verify firewall rules allow HTTPS traffic to GitHub
   • Test with: curl -I https://api.github.com

3. Repository State

   • Ensure the repository has an initialized default branch
   • Check that the branch name in your configuration matches the actual default branch
   • Verify the GitHub App has access to the specific branch

4. Entity Eligibility

   • Only organization-level entities (without specific owners) are synced to GitHub
   • Check if you have any organization-level entities in your database
   • User-specific or private entities are intentionally excluded from sync
   • MCP Clients do not have an owner_id field and are always synced

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 configuration repository
   • Use "Only select repositories" instead of "All repositories"
   • Review app permissions regularly

4. Sensitive Data Handling

   • MCP Server auth credentials (API keys, secrets, OAuth) are automatically excluded from sync
   • Never manually add sensitive data to your GitHub repository
   • Use your database/admin panel for managing authentication settings

5. Monitor Access

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

Additional Resources

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