Feature: GitHub Integration #1132

New issue

Open

opened 2025-10-14 16:57:06 -06:00 by navan · 0 comments

navan commented

2025-10-14 16:57:06 -06:00

Owner

Originally created by @eyaltoledano on 3/24/2025

Motivation

TaskMaster currently relies on local files (tasks.json and individual task files) to manage tasks. This approach is effective and straightforward for individual developers, but it quickly breaks down in team scenarios. Specifically, local storage causes merge conflicts when multiple developers add tasks simultaneously across different branches.

To address this limitation and enable "TaskMaster Multiplayer," we propose integrating GitHub Projects to serve as a centralized task management backend.

Proposed Solution

Add an option to TaskMaster CLI to use external task management backends (starting with GitHub Projects), in addition to the existing local storage approach. Tasks would then be sourced from GitHub Issues instead of local files.

This integration would significantly improve collaborative workflows by eliminating task conflicts, providing centralized task storage, and allowing two-way synchronization between GitHub Projects and the CLI.

Key Elements

Centralized Task Database: Use GitHub Projects and Issues as the primary source of tasks, replacing local files (tasks.json and task files).
Configurable Backend: Allow the user to choose between:
- Local task storage (current behavior).
- GitHub Projects (new integration).
- Future support for other services like Trello, Asana, Linear, etc.
Benefits:
- Eliminates merge conflicts associated with local task storage.
- Allows collaboration ("TaskMaster Multiplayer") with tasks visible to the whole team.
- Enables users to manage tasks directly via GitHub’s UI, providing an additional interface.
- Potential for seamless two-way synchronization (CLI <-> GitHub).
Implementation Considerations:
- Requires GitHub token stored securely (e.g., in an environment variable).
- Introduces latency due to network/API calls, mitigated through caching or optimized SDK usage.
- Each task would correspond to a unique branch and Pull Request (PR).
- Major effort: requires updating ~20 existing CLI commands to support remote task storage.
- Create a reusable GitHubService class wrapping GitHub’s SDK to abstract API interactions.

Example Workflow

User creates a new task using TaskMaster CLI.
CLI creates a corresponding GitHub Issue and branch.
Developers collaborate via GitHub Projects UI or CLI commands.
When tasks are updated via GitHub (e.g., status change, comments), CLI reflects these updates locally upon sync.
Merging branches becomes straightforward, avoiding the issues seen with local JSON files.

New Commands or Flags

task-master sync: Synchronize tasks from GitHub Projects to local CLI (bi-directional).
Potential new flags (--backend=github) on task-related commands (e.g., add, update, complete) to specify the active backend.

Out of Scope (Future Considerations)

Integration with other task/project management tools via MCP or custom wrappers (e.g., Trello, Linear).
Real-time sync optimizations or advanced caching layers to reduce latency.

Feedback Wanted

Does this clearly solve the issues encountered with local storage?
Are there any additional considerations or edge cases I may have missed?
Suggestions regarding the usability or UX of choosing between local storage and external services

*Originally created by @eyaltoledano on 3/24/2025* ## Motivation TaskMaster currently relies on local files (`tasks.json` and individual task files) to manage tasks. This approach is effective and straightforward for individual developers, but it quickly breaks down in team scenarios. Specifically, local storage causes merge conflicts when multiple developers add tasks simultaneously across different branches. To address this limitation and enable "TaskMaster Multiplayer," we propose integrating GitHub Projects to serve as a centralized task management backend. ## Proposed Solution Add an option to TaskMaster CLI to use external task management backends (starting with GitHub Projects), in addition to the existing local storage approach. Tasks would then be sourced from GitHub Issues instead of local files. This integration would significantly improve collaborative workflows by eliminating task conflicts, providing centralized task storage, and allowing two-way synchronization between GitHub Projects and the CLI. ## Key Elements - **Centralized Task Database**: Use GitHub Projects and Issues as the primary source of tasks, replacing local files (`tasks.json` and task files). - **Configurable Backend**: Allow the user to choose between: - Local task storage (current behavior). - GitHub Projects (new integration). - Future support for other services like Trello, Asana, Linear, etc. - **Benefits**: - Eliminates merge conflicts associated with local task storage. - Allows collaboration ("TaskMaster Multiplayer") with tasks visible to the whole team. - Enables users to manage tasks directly via GitHub’s UI, providing an additional interface. - Potential for seamless two-way synchronization (CLI <-> GitHub). - **Implementation Considerations**: - Requires GitHub token stored securely (e.g., in an environment variable). - Introduces latency due to network/API calls, mitigated through caching or optimized SDK usage. - Each task would correspond to a unique branch and Pull Request (PR). - Major effort: requires updating ~20 existing CLI commands to support remote task storage. - Create a reusable `GitHubService` class wrapping GitHub’s SDK to abstract API interactions. ## Example Workflow - User creates a new task using TaskMaster CLI. - CLI creates a corresponding GitHub Issue and branch. - Developers collaborate via GitHub Projects UI or CLI commands. - When tasks are updated via GitHub (e.g., status change, comments), CLI reflects these updates locally upon sync. - Merging branches becomes straightforward, avoiding the issues seen with local JSON files. ## New Commands or Flags - `task-master sync`: Synchronize tasks from GitHub Projects to local CLI (bi-directional). - Potential new flags (`--backend=github`) on task-related commands (e.g., `add`, `update`, `complete`) to specify the active backend. ## Out of Scope (Future Considerations) - Integration with other task/project management tools via MCP or custom wrappers (e.g., Trello, Linear). - Real-time sync optimizations or advanced caching layers to reduce latency. ## Feedback Wanted - Does this clearly solve the issues encountered with local storage? - Are there any additional considerations or edge cases I may have missed? - Suggestions regarding the usability or UX of choosing between local storage and external services