Skip to main content

GitHub Integration Troubleshooting

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 CodeHTTP CodeDescriptionResolution
INVALID_JSON400The JSON file contains invalid syntaxFix JSON syntax errors in the file
VALIDATION_FAILED400Required fields (name or slug) are missingAdd missing required fields to the entity
EMPTY_DIRECTORY400Skill directory is empty or missing SKILL.mdAdd SKILL.md file to the skill directory
MISSING_INTEGRATION400Referenced integration doesn't exist in your organizationAdd the integration or update the toolkit to use existing integrations
MISSING_TOOL400Referenced tool doesn't exist in the integrationCheck tool slugs match available tools in the integration
FETCH_FAILED500Failed to fetch the file from GitHubCheck 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 (toolkits/, commands/, 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
On this page