GitHub Sync

Bidirectional sync between Gnoll and GitHub Issues. Push local issues to GitHub, pull GitHub issues into Gnoll, or sync both ways.

Overview

GitHub Sync connects a Gnoll project to a GitHub repository. Issues can flow in either direction:

• Push — Local issues are created/updated as GitHub issues
• Pull — GitHub issues are imported/updated as local issues
• Bidirectional — Both push and pull in each sync cycle

Linked issues are tracked via External References, so duplicates are avoided on subsequent syncs.

Setup

Configure GitHub Sync from the Settings page under GitHub Sync, or via the API.

Requirements

• A GitHub Personal Access Token with repo scope (or fine-grained token with Issues read/write)
• The repository owner and repo name

Configuration Options

How Sync Works

Push (Local → GitHub)

1. Finds all issues in the project
2. For issues without a GitHub reference — creates a new GitHub issue
3. For issues already linked — updates the existing GitHub issue
4. Stores the GitHub issue URL as an external reference

Pull (GitHub → Local)

1. Fetches all issues from the GitHub repo (paginated)
2. For issues already linked — updates the local issue (title, description, status)
3. For new GitHub issues — creates a local issue and stores the reference
4. Maps GitHub labels to local labels (auto-created if needed)

Status Mapping

Background Sync

A background service runs every 15 minutes and automatically syncs all enabled GitHub configurations. No manual triggering required for ongoing sync.

API Endpoints

Get current GitHub sync configuration.

Configure or update GitHub sync settings.

{
  "owner": "myorg",
  "repo": "my-project",
  "token": "ghp_...",
  "syncDirection": "bidirectional",
  "conflictResolution": "last_write_wins",
  "isEnabled": true
}

Trigger a manual sync immediately. Returns push and pull counts.

Get sync status including last sync time and linked issue count.

Remove GitHub sync configuration.

MCP Tools