firefrost-operations-manual/docs/procedures/task-to-issue-automation.md

Task to Gitea Issue Automation

Created: March 20, 2026
Created By: The Chronicler #36
Purpose: Automatically create Gitea issues whenever tasks are added to docs/core/tasks.md

---

Overview

This automation ensures that every task in docs/core/tasks.md has a corresponding Gitea issue on the Kanban board. No more manual issue creation!

How It Works

1. You edit docs/core/tasks.md and add a new task
2. You commit the changes to Git
3. Pre-commit hook detects the change and runs scripts/sync-tasks-to-issues.py
4. Script parses tasks.md and creates missing Gitea issues
5. Issues created with appropriate labels (status, priority, type, area, assignee)
6. Issues appear in Gitea with status/backlog label

---

Components

1. Main Sync Script

Location: scripts/sync-tasks-to-issues.py

What it does:

• Parses docs/core/tasks.md to extract all tasks
• Checks which tasks already have Gitea issues
• Creates missing issues with smart label detection
• Applies labels based on task content:
  • Status: Detects COMPLETE, BLOCKED, IN PROGRESS, or defaults to backlog
  • Priority: Detects from Tier 0/1/2/3 or HIGH/MEDIUM/LOW keywords
  • Assignees: Detects Michael/Meg/Holly mentions
  • Areas: Detects Ghost/Pterodactyl/Mailcow/etc.
  • Type: Detects task/feature/bug/infrastructure/docs

Usage:

# Dry run (see what would be created)
python3 scripts/sync-tasks-to-issues.py --dry-run

# Actually create issues
python3 scripts/sync-tasks-to-issues.py

# From anywhere in the repo
cd /path/to/firefrost-operations-manual
python3 scripts/sync-tasks-to-issues.py

2. Git Pre-Commit Hook

Location: .git/hooks/pre-commit

What it does:

• Automatically runs before every commit
• Detects if docs/core/tasks.md was modified
• Runs the sync script automatically
• Commits proceed even if sync fails (with warning)

Installation: Already installed! The hook is in .git/hooks/pre-commit and is executable.

---

Workflow for Adding New Tasks

Step 1: Add Task to tasks.md

Edit docs/core/tasks.md and add your task:

### 67. Deploy New Modpack Server
**Time:** 2-3 hours  
**Status:** READY  
**Priority:** HIGH  
**Documentation:** `docs/tasks/new-modpack-deployment/`

Deploy the Eternal Skyforge modpack to TX1 Dallas server for soft launch.

**Key Deliverables:**
- Server installed and configured
- Whitelisted and tested
- Added to Paymenter tier

**Dependencies:**
- Task #2 (Rank system deployment)
- Server hardware available on TX1

Step 2: Commit the Change

cd /path/to/firefrost-operations-manual
git add docs/core/tasks.md
git commit -m "feat: add Task #67 - Deploy New Modpack Server"

Step 3: Automation Runs

The pre-commit hook automatically:

1. Detects the tasks.md change
2. Runs the sync script
3. Creates Gitea issue for Task #67
4. Applies labels based on content

You'll see output like:

🔥❄️ Detected changes to tasks.md - syncing to Gitea issues...
📋 Parsed 67 tasks from docs/core/tasks.md
🔍 Found 66 existing task issues
  ✅ Created issue #86: Task #67 - Deploy New Modpack Server
✅ Task sync complete

Step 4: Push to Gitea

git push origin master

Done! Your task now exists as both:

• Documentation in docs/core/tasks.md
• Gitea issue on the Kanban board (with status/backlog label)

---

Label Detection Logic

The script is smart about applying labels based on task content:

Status Detection

• Contains "✅ COMPLETE" → status/done
• Contains "BLOCKED" → status/blocked
• Contains "IN PROGRESS" → status/in-progress
• Default: → status/backlog

Priority Detection

• Contains "Tier 0" or "TOP PRIORITY" or "critical" → priority/critical
• Contains "HIGH" or "Priority: High" → priority/high
• Contains "Tier 2" or "MEDIUM" → priority/medium
• Contains "Tier 3" or "LOW" → priority/low
• Default: → priority/medium

Assignee Detection

• Mentions "Michael" or "Frostystyle" → for/michael
• Mentions "Meg" or "GingerFury" or "Emissary" → for/meg
• Mentions "Holly" or "unicorn" or "Builder" → for/holly
• Default: → for/michael

Area Detection

• Mentions "Ghost" or "website" or "homepage" → area/website
• Mentions "Pterodactyl" or "Panel" → area/panel
• Mentions "Wings" or "game server" → area/wings
• Mentions "Mailcow" or "email" → area/email
• Mentions "Paymenter" or "billing" → area/billing
• Mentions "n8n" or "automation" → area/automation
• Mentions "network" or "firewall" → area/networking
• Default: → area/operations

Type Detection

• Mentions "bug" or "fix" → type/bug
• Mentions "feature" or "new" → type/feature
• Mentions "infrastructure" or "deploy" or "server" → type/infrastructure
• Mentions "documentation" or "docs" or "guide" → type/docs
• Default: → type/task

---

Manual Sync (If Needed)

If you need to manually sync tasks to issues (e.g., after bulk changes):

cd /path/to/firefrost-operations-manual

# Preview what would be created
python3 scripts/sync-tasks-to-issues.py --dry-run

# Actually create missing issues
python3 scripts/sync-tasks-to-issues.py

---

Troubleshooting

Hook Not Running

If the pre-commit hook doesn't run:

# Check if hook exists and is executable
ls -la .git/hooks/pre-commit

# If not executable:
chmod +x .git/hooks/pre-commit

Script Fails

If the sync script fails:

# Check Python is available
python3 --version

# Check requests library is installed
python3 -c "import requests; print('OK')"

# If not installed:
pip3 install requests --break-system-packages

# Run with verbose output
python3 scripts/sync-tasks-to-issues.py

Issues Not Appearing on Kanban

Known Limitation: Gitea's API doesn't support adding issues to project boards programmatically (as of Gitea v1.21.5).

Current Workflow:

1. Script creates issues with proper labels
2. Issues appear in regular issue list
3. Manual step required: Add issues to "Firefrost Operations" project board via web UI

Future Enhancement: Investigate Gitea API updates or create web automation to add issues to project board.

---

Future Enhancements

Potential improvements for future Chroniclers:

1. Project Board Automation: Auto-add issues to project board (requires Gitea API update or web automation)
2. Bidirectional Sync: Update tasks.md when issues are modified in Gitea
3. Issue Templates: Auto-create task directory structure in docs/tasks/
4. Webhook Integration: Trigger sync on Gitea push instead of pre-commit
5. Label Management: Auto-create missing labels if they don't exist

---

Technical Details

Gitea API Endpoints Used

GET  /api/v1/repos/{owner}/{repo}/issues?state=all&limit=200
POST /api/v1/repos/{owner}/{repo}/issues
PUT  /api/v1/repos/{owner}/{repo}/issues/{number}/labels

Label IDs (Current as of March 2026)

LABEL_IDS = {
    'status/backlog': 2,
    'status/to-do': 3,
    'status/in-progress': 4,
    'status/review': 5,
    'status/blocked': 6,
    'status/done': 7,
    'priority/critical': 8,
    'priority/high': 9,
    'priority/medium': 10,
    'priority/low': 11,
    # ... (see script for complete list)
}

Note: If labels are added/removed in Gitea, update the LABEL_IDS dictionary in the script.

---

Credits

Created By: The Chronicler #36
Date: March 20, 2026
Inspired By: The need to automate what previous Chroniclers did manually
Philosophy: "If it's not automated, it will be forgotten"

---

Fire + Frost + Foundation = Automation That Outlasts Us 💙🔥❄️