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 |
| Guards | guards/ | JSON files | One file per guard; catalog check lists included for automatic guards |
| Config deployment | <agent>/<file>/ | Folder per rule | meta.json and config.json per rule; push only. See Config Deployment |
| 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.
Sync Mode
Each entity type has its own sync mode and repository under Settings > Git Integration, so you can, for example, keep guards in two-way sync while MCP servers only push to Git.
| Mode | Willow to Git | Git to Willow |
|---|---|---|
| Disabled | No | No |
| Two-way sync | Yes | Yes |
| Push to GitHub | Yes | No. Commits made directly in the repository are ignored |
| Pull from GitHub | No | Yes, from webhook pushes and the on-demand Pull from GitHub button |
Config deployment can only be set to Disabled or Push to GitHub, because it has nothing to pull back.
On a Bitbucket connection the options read Push to Bitbucket and Pull from Bitbucket.
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 - Guards: Synced as
guards/{slug}.json. Automatic guards are written with their full catalog check list; on import from GitHub, checks are compared to the catalog and flagged asmodifiedif changed orcustomif not recognized. - Plugins: Synced as directory
plugins/{slug}/with the platform manifest and the plugin's bundled skills, commands, rules, hooks, sub-agents, and MCP config - Config deployment: Every rule change is committed as
{agent}/{file}/{rule}/meta.jsonandconfig.json, so the repository history is a change log. Push only; available while config deployment is enabled for your organization. See Config Deployment
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}/
Only pushes to the repository's default branch are processed. When a pushed commit removes an entity's file, Willow deletes that entity, as long as its type is in Two-way sync or Pull from GitHub mode. This can happen without anyone deleting the file on purpose, for example when an old branch that never had it is merged into the default branch. Check Monitor > Logs > Git logs to see which push removed it. A deleted MCP server can be restored from Deleted MCP Servers, at /integrations/deleted in the admin app. If the repository is only a backup, set the entity types to Push to GitHub so commits made in the repository can never delete anything in Willow.
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