GitHub Integration
Connect a GitHub repository to automatically sync your organization's configuration. When enabled, your toolkits, skills, commands, MCP servers, MCP clients, and plugins are stored as code in your repository, so you can version control and track changes.
Only organization-level entities (without specific owners) are synced to GitHub. User-specific or private entities remain in the database only.
Configure it under Admin > Settings > Git Integration, which also supports Bitbucket.
What Gets Synced
The GitHub integration syncs the following entity types:
| Entity Type | Directory | Format | Notes |
|---|---|---|---|
| Toolkits | toolkits/ | JSON files | One file per toolkit |
| Commands | commands/ | JSON files | One file per command |
| MCP Servers | mcp-servers/ | JSON files | Auth credentials excluded for security |
| MCP Clients | mcp-clients/ | JSON files | One file per client |
| Skills | skills/ | Directory per skill | Contains SKILL.md, scripts, references |
| Plugins | plugins/ | Directory per plugin | One plugins/{slug}/ folder per plugin, containing its platform manifest plus bundled skills, commands, rules, hooks, sub-agents, and MCP config |
Authentication settings for MCP servers (API keys, secrets, OAuth credentials) are never synced to GitHub for security reasons. Only the configuration structure is synced.
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
How It Works
Automatic Sync (Database → GitHub)
When you create or update any entity in your admin panel:
- The entity is saved to the database
- A background job pushes the change to GitHub
- A commit is created with descriptive message
Supported operations:
- Toolkits: Synced as
toolkits/{slug}.json - Commands: Synced as
commands/{slug}.json - Skills: Synced as directory
skills/{slug}/with SKILL.md, scripts, references, and assets - MCP Servers: Synced as
mcp-servers/{slug}.json(auth credentials excluded) - MCP Clients: Synced as
mcp-clients/{slug}.json - Plugins: Synced as directory
plugins/{slug}/with the platform manifest and the plugin's bundled skills, commands, rules, hooks, sub-agents, and MCP config
Webhook Sync (GitHub → Database)
When you push changes directly to GitHub:
- GitHub sends a webhook notification
- Your application validates the webhook signature
- Modified files are detected and classified by type
- Files are parsed and entities are updated in the database
- 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
skills/{slug}/ - Plugin directories are reconstructed from all files in
plugins/{slug}/
The bidirectional sync above keeps a connected repository and Willow in step. To pull plugins from other GitHub repositories on demand or on a daily schedule, see Sync Plugins from GitHub.
What to do next
- Set Up the GitHub Integration: create the GitHub App and connect it
- Troubleshooting: error types, fixes, and security practices