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 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/repoformat
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
- Check webhook deliveries in GitHub App settings
- Look for failed webhook requests (red X). If there are no deliveries at all, the app isn't sending events: open the app's Permissions & events page and confirm Push is checked under Subscribe to events (see Step 7).
- Verify the webhook URL is correct and accessible
- Check your application logs for webhook processing errors
- Ensure files are in the correct directories (
toolkits/,commands/,skills/, etc.) - To see which pushes Willow received and what it did with them, open Monitor > Logs, then Views > All views... > Audit > Git logs.
An entity disappeared from Willow after a merge or push
A push to the default branch that removes an entity's file deletes the entity in Willow when its type syncs from GitHub (Two-way sync or Pull from GitHub). Look in Monitor > Logs > Git logs for the push at that time, and check whether the file was missing from the commits, for example because an old branch was merged. A deleted MCP server can be brought back from /integrations/deleted in the admin app (Deleted MCP Servers); for other entity types, restore the file in the repository and push. To stop commits in the repository from deleting anything, switch the entity type to Push to GitHub. See Sync Mode.
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
mainormaster)
"Permission denied"
- Verify the GitHub App has
Contents: Read and writepermission - 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:
-
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
-
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
-
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
-
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_idfield and are always synced
Security Best Practices
-
Private Key Management
- Never commit the private key to version control
- Store it securely (encrypted environment variables or secrets manager)
- Rotate keys periodically
-
Webhook Secrets
- Always use webhook secrets in production
- Use a cryptographically secure random string
- Rotate secrets if they're ever exposed
-
Repository Permissions
- Grant the GitHub App access only to the configuration repository
- Use "Only select repositories" instead of "All repositories"
- Review app permissions regularly
-
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
-
Monitor Access
- Regularly review GitHub App installations
- Check webhook delivery logs for suspicious activity
- Audit configuration changes through Git history