Skip to main content

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.

info

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 TypeDirectoryFormatNotes
Toolkitstoolkits/JSON filesOne file per toolkit
Commandscommands/JSON filesOne file per command
MCP Serversmcp-servers/JSON filesAuth credentials excluded for security
MCP Clientsmcp-clients/JSON filesOne file per client
Skillsskills/Directory per skillContains SKILL.md, scripts, references
Guardsguards/JSON filesOne file per guard; catalog check lists included for automatic guards
Config deployment<agent>/<file>/Folder per rulemeta.json and config.json per rule; push only. See Config Deployment
Pluginsplugins/Directory per pluginOne plugins/{slug}/ folder per plugin, containing its platform manifest plus bundled skills, commands, rules, hooks, sub-agents, and MCP config
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.

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.

ModeWillow to GitGit to Willow
DisabledNoNo
Two-way syncYesYes
Push to GitHubYesNo. Commits made directly in the repository are ignored
Pull from GitHubNoYes, 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:

  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 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 as modified if changed or custom if 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.json and config.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:

  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 skills/{slug}/
  • Plugin directories are reconstructed from all files in plugins/{slug}/
Removing a file deletes the entity

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.

Importing plugins from an external repo

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​

Additional Resources​