📋 Issue Tracker

A Bash script that syncs your TASKS.md file with GitHub and Gitea/Codeberg issues automatically. Manage all your tasks in a simple Markdown checklist and let the script handle issue creation, updates, and closure across multiple platforms.

✨ Features

• 📝 Single Source of Truth - Manage all tasks in one TASKS.md file
• 🔄 Multi-Platform Sync - Works with GitHub (org & personal) and Gitea/Codeberg
• 🎯 Smart Operations - Creates, updates, and closes issues automatically
• 🔒 Secure - Credentials stored in .env file (never committed)
• 🍎 macOS Compatible - Works with Bash 3.2+ (macOS default)
• 🎓 Teaching-Friendly - Extensively commented for learning
• 🚀 Zero Dependencies - Only requires bash, curl, and jq

🚀 Quick Start

Prerequisites

• Bash 3.2 or higher
• curl (usually pre-installed)
• jq (installation guide)

Installation

1. Clone this repository:

git clone https://github.com/octokas/issue-tracker.git
cd issue-tracker

2. Copy the example files:

cp .env.example .env
cp TASKS.md.example TASKS.md

3. Configure your credentials in .env:

# Edit .env with your tokens and repositories
nano .env

4. Make the script executable:

chmod +x issue-tracker.sh

Usage

1. Add tasks to TASKS.md using this format:

- [ ] (P1) [feature] Add user login - @username - est: 2h - due: 2025-12-31

2. Run the sync script:

./issue-tracker.sh

3. Watch as issues are created/updated/closed across your platforms! 🎉

📖 Task Format

- [ ] (P#) [type] Title - @assignee - est: time - due: YYYY-MM-DD

Components:

• [ ] = Open task, [x] = Completed task
• (P0-P3) = Priority (P0=critical, P1=high, P2=medium, P3=low)
• [type] = feature, bug, or chore
• @assignee = GitHub/Gitea username
• est: = Estimated time (e.g., 2h, 1d, 3d)
• due: = Due date (YYYY-MM-DD)

Example:

- [ ] (P0) [bug] Fix authentication timeout - @johndoe - est: 4h - due: 2025-12-28
- [x] (P1) [feature] Add dark mode - @janedoe - est: 1d - due: 2025-12-20

🔧 Configuration

Platform Setup

The script supports three platforms simultaneously:

1. GitHub Organization - For team/org repositories
2. GitHub Personal - For your personal repositories
3. Gitea/Codeberg - For self-hosted or Codeberg repos

Configure each in your .env file (see .env.example).

Generating Access Tokens

GitHub:

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token"
3. Select scopes: repo (full control)
4. Copy the token to your .env file

Gitea/Codeberg:

1. Go to Settings → Applications → Generate New Token
2. Give it a name and select scopes
3. Copy the token to your .env file

Assignee Mapping

The script includes platform-specific assignee mapping. Edit lines 179-181 and 305-307 to customize:

# Example: Map awestomates to octokas for GitHub platforms
if [[ "$name" == "githubpersonal" || "$name" == "githuborg" ]] && [[ "$assignee" == "awestomates" ]]; then
    assignee="octokas"
fi

🎯 How It Works

1. Parse - Reads TASKS.md and extracts open [ ] and completed [x] tasks
2. Fetch - Gets existing issues from each configured platform
3. Sync - For each platform:
   • Creates issues for new tasks
   • Updates issues when task details change
   • Closes issues when tasks are marked complete
   • Skips issues that are already in sync
4. Report - Shows a summary of all operations

🎓 Learning Resources

This script is designed to be teaching-friendly with:

• Numbered sections and subsections
• Detailed inline comments
• Clear variable naming
• Examples of common Bash patterns

Perfect for learning:

• Bash scripting fundamentals
• API interactions with curl
• JSON processing with jq
• Regex pattern matching
• Parallel array data structures
• Error handling and defensive programming

🤝🏼 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

What this means:

• ✅ Free to use for any purpose
• ✅ Can modify and distribute
• ✅ Must keep modifications open source
• ❌ Cannot be sold as proprietary software

🙏🏼 Acknowledgments

Built with love for developers who prefer simple, transparent tools over complex systems.

📞 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

---

Made with 💞 and Bash | Star ⭐ this repo if you find it helpful!