sivertio/kanbn-github-sync repository overview

⁠Repository Overview

⁠Kanbn GitHub Sync (KGS)

Automated GitHub issue synchronization to Kanbn with intelligent board management and real-time updates.

🔗 GitHub Repository⁠

Kanbn GitHub Sync is a TypeScript-based service that automatically synchronizes GitHub issues to Kanbn kanban boards. It eliminates manual board setup by automatically creating boards and lists for each repository, intelligently organizing issues based on their status, and keeping cards in sync with real-time updates.

⁠Key Capabilities

⁠🤖 Fully Automated Setup

• Zero Configuration - Automatically creates boards and lists for each repository
• Smart Organization - Issues are intelligently assigned to lists based on GitHub status
• Multi-Repository Support - Sync multiple repositories simultaneously with dedicated boards per repo

⁠🔄 Intelligent Synchronization

• Real-Time Updates - Polls GitHub every minute (configurable) and syncs changes
• Status Tracking - Cards automatically move between lists as issue status changes
• Label Sync - GitHub labels are automatically synced to Kanbn labels
• Duplicate Prevention - Prevents duplicate cards even after service restarts

⁠🎯 Smart List Assignment

Issues are automatically organized into lists based on their GitHub status:

• Closed issues → Completed/Closed
• Issues with branches/PRs → In Progress
• Assigned issues → Selected
• New issues → Backlog

⁠🏗️ Technical Highlights

• TypeScript - Type-safe codebase with modern Node.js features
• Docker-Ready - Containerized deployment with multi-platform support (linux/amd64, linux/arm64)
• Rate Limit Handling - Intelligent handling of GitHub API rate limits with retry logic
• Hot Reload - Configuration changes reload automatically without service restart
• REST API - Optional HTTP server for health checks and manual sync triggers

⁠Architecture

The service operates in two distinct phases:

1. Setup Phase - Creates all boards and lists for configured repositories
2. Sync Phase - Fetches issues from GitHub and syncs them to Kanbn cards

This approach ensures infrastructure is ready before syncing data, preventing errors and improving reliability.

⁠Use Cases

• Project Management - Keep all GitHub issues organized in a kanban board for better visibility
• Multi-Repository Workflows - Centralize issue tracking across multiple repositories
• Status Visualization - Visualize issue status and progress with automatic list assignment
• Team Collaboration - Share issue status with team members using Kanbn's interface

⁠Technology Stack

• Runtime: Node.js 18+ (with native fetch support)
• Language: TypeScript 5.3+
• Framework: Express.js (optional HTTP server)
• Containerization: Docker with multi-platform builds
• Package Manager: Yarn

⁠Deployment

Supports multiple deployment methods:

• Native Node.js - Run directly with yarn start
• Docker Compose - Production-ready containerized deployment
• Docker Hub - Pre-built images available at sivertio/kanbn-github-sync

⁠Requirements

• Node.js 18+ (or Docker for containerized deployment)
• A running Kanbn instance
• Kanbn API key
• GitHub repositories to sync

⁠License

MIT License - Open source and free to use