firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

feat: task-to-issue automation system

Browse Source 
- Created scripts/sync-tasks-to-issues.py for automatic Gitea issue creation
- Added Git pre-commit hook to auto-sync on tasks.md changes
- Smart label detection based on task content (status, priority, assignees, areas)
- Created comprehensive documentation in docs/procedures/task-to-issue-automation.md
- Synced all missing tasks (#1-9, #21-27) to Gitea issues (#86-101)

This ensures every task in docs/core/tasks.md automatically gets a Gitea issue
on the Kanban board with appropriate labels. No more manual issue creation!

Created by: The Chronicler #36
Standard: FFG-STD-001 (Revision Control)
This commit is contained in:
Claude
2026-03-21 02:06:08 +00:00
parent 13e91177de
commit 88e0fe0661
2 changed files with 635 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

285
docs/procedures/task-to-issue-automation.md Normal file
View File

@@ -0,0 +1,285 @@
# 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:**
```bash
# 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:
```markdown
### 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
```bash
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
```bash
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):
```bash
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:
```bash
# 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:
```bash
# 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)
```python
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** 💙🔥❄️

350
scripts/sync-tasks-to-issues.py Executable file
View File

@@ -0,0 +1,350 @@
#!/usr/bin/env python3
"""
Firefrost Gaming - Task to Gitea Issue Synchronization
Automatically creates/updates Gitea issues based on docs/core/tasks.md
This script:
1. Parses docs/core/tasks.md to extract all tasks
2. Checks which tasks have corresponding Gitea issues
3. Creates missing issues with appropriate labels
4. Updates existing issues if task details changed
Usage:
python3 scripts/sync-tasks-to-issues.py [--dry-run] [--force]
"""
import requests
import json
import re
import sys
import argparse
from typing import Dict, List, Optional, Set
# Configuration
GITEA_URL = "https://git.firefrostgaming.com"
GITEA_TOKEN = "e0e330cba1749b01ab505093a160e4423ebbbe36"
REPO_OWNER = "firefrost-gaming"
REPO_NAME = "firefrost-operations-manual"
TASKS_FILE = "docs/core/tasks.md"
# Label IDs (from Gitea API)
LABEL_IDS = {
'area/automation': 23,
'area/billing': 20,
'area/email': 21,
'area/game-servers': 25,
'area/networking': 24,
'area/operations': 26,
'area/panel': 18,
'area/website': 22,
'area/wings': 19,
'for/holly': 27,
'for/meg': 28,
'for/michael': 29,
'priority/critical': 8,
'priority/high': 9,
'priority/low': 11,
'priority/medium': 10,
'status/backlog': 2,
'status/blocked': 6,
'status/done': 7,
'status/in-progress': 4,
'status/review': 5,
'status/to-do': 3,
'type/bug': 12,
'type/docs': 15,
'type/feature': 13,
'type/infrastructure': 16,
'type/refactor': 17,
'type/task': 14,
}
headers = {
"Authorization": f"token {GITEA_TOKEN}",
"Content-Type": "application/json"
}
class Task:
"""Represents a task from tasks.md"""
def __init__(self, number: int, title: str, content: str):
self.number = number
self.title = title
self.content = content
self.status = self._parse_status()
self.priority = self._parse_priority()
self.time_estimate = self._parse_time()
self.assignees = self._parse_assignees()
self.areas = self._parse_areas()
self.task_type = self._parse_type()
def _parse_status(self) -> str:
"""Extract status from task content"""
if '✅ COMPLETE' in self.content:
return 'status/done'
if '**Status:** BLOCKED' in self.content or 'blocked' in self.content.lower():
return 'status/blocked'
if '**Status:** IN PROGRESS' in self.content:
return 'status/in-progress'
# Default to backlog for new tasks
return 'status/backlog'
def _parse_priority(self) -> str:
"""Extract priority from task content"""
content_lower = self.content.lower()
if 'priority: top' in content_lower or 'tier 0' in content_lower or 'critical' in content_lower:
return 'priority/critical'
if 'priority: high' in content_lower or 'high priority' in content_lower:
return 'priority/high'
if 'priority: medium' in content_lower or 'tier 2' in content_lower:
return 'priority/medium'
if 'priority: low' in content_lower or 'tier 3' in content_lower:
return 'priority/low'
# Default to medium
return 'priority/medium'
def _parse_time(self) -> Optional[str]:
"""Extract time estimate"""
match = re.search(r'\*\*Time:\*\*\s*([^\n]+)', self.content)
return match.group(1).strip() if match else None
def _parse_assignees(self) -> List[str]:
"""Extract assignees from task content"""
assignees = []
content_lower = self.content.lower()
if 'michael' in content_lower or 'frostystyle' in content_lower:
assignees.append('for/michael')
if 'meg' in content_lower or 'gingerfury' in content_lower or 'emissary' in content_lower:
assignees.append('for/meg')
if 'holly' in content_lower or 'unicorn' in content_lower or 'builder' in content_lower:
assignees.append('for/holly')
# Default to Michael if no assignee found
if not assignees:
assignees.append('for/michael')
return assignees
def _parse_areas(self) -> List[str]:
"""Extract area labels from task content"""
areas = []
content_lower = self.content.lower()
if 'ghost' in content_lower or 'website' in content_lower or 'homepage' in content_lower:
areas.append('area/website')
if 'pterodactyl' in content_lower or 'panel' in content_lower:
areas.append('area/panel')
if 'wings' in content_lower or 'game server' in content_lower:
areas.append('area/wings')
if 'mailcow' in content_lower or 'email' in content_lower:
areas.append('area/email')
if 'paymenter' in content_lower or 'billing' in content_lower:
areas.append('area/billing')
if 'n8n' in content_lower or 'automation' in content_lower or 'workflow' in content_lower:
areas.append('area/automation')
if 'network' in content_lower or 'firewall' in content_lower or 'tunnel' in content_lower:
areas.append('area/networking')
# Default to operations if no specific area
if not areas:
areas.append('area/operations')
return areas
def _parse_type(self) -> str:
"""Extract task type"""
content_lower = self.content.lower()
if 'bug' in content_lower or 'fix' in content_lower:
return 'type/bug'
if 'feature' in content_lower or 'new' in content_lower:
return 'type/feature'
if 'infrastructure' in content_lower or 'deploy' in content_lower or 'server' in content_lower:
return 'type/infrastructure'
if 'documentation' in content_lower or 'docs' in content_lower or 'guide' in content_lower:
return 'type/docs'
# Default to task
return 'type/task'
def get_label_ids(self) -> List[int]:
"""Get all label IDs for this task"""
label_names = [self.status, self.priority, self.task_type] + self.assignees + self.areas
return [LABEL_IDS[name] for name in label_names if name in LABEL_IDS]
def to_issue_body(self) -> str:
"""Convert task content to issue body"""
body = f"### Task #{self.number}: {self.title}\n\n"
if self.time_estimate:
body += f"**Time Estimate:** {self.time_estimate}\n\n"
body += f"**Documentation:** `docs/tasks/` (see operations manual)\n\n"
body += "---\n\n"
body += self.content.strip()
body += f"\n\n---\n\n**Source:** `docs/core/tasks.md` (Task #{self.number})"
return body
def parse_tasks_file() -> List[Task]:
"""Parse docs/core/tasks.md and extract all tasks"""
tasks = []
try:
with open(TASKS_FILE, 'r') as f:
content = f.read()
except FileNotFoundError:
print(f"❌ Error: {TASKS_FILE} not found")
return []
# Split by task headers (### N. Title)
task_pattern = r'###\s+(\d+)\.\s+([^\n]+)\n(.*?)(?=\n###\s+\d+\.|\Z)'
matches = re.findall(task_pattern, content, re.DOTALL)
for match in matches:
number = int(match[0])
title = match[1].strip()
task_content = match[2].strip()
tasks.append(Task(number, title, task_content))
print(f"📋 Parsed {len(tasks)} tasks from {TASKS_FILE}")
return tasks
def get_existing_issues() -> Dict[int, dict]:
"""Fetch all existing issues and map them by task number"""
url = f"{GITEA_URL}/api/v1/repos/{REPO_OWNER}/{REPO_NAME}/issues?state=all&limit=200"
try:
response = requests.get(url, headers=headers)
response.raise_for_status()
issues = response.json()
except Exception as e:
print(f"❌ Error fetching issues: {e}")
return {}
# Map issues by task number extracted from title
issue_map = {}
for issue in issues:
title = issue['title']
match = re.search(r'Task #(\d+):', title)
if match:
task_num = int(match.group(1))
issue_map[task_num] = issue
print(f"🔍 Found {len(issue_map)} existing task issues")
return issue_map
def create_issue(task: Task, dry_run: bool = False) -> bool:
"""Create a Gitea issue for the task"""
url = f"{GITEA_URL}/api/v1/repos/{REPO_OWNER}/{REPO_NAME}/issues"
data = {
"title": f"Task #{task.number}: {task.title}",
"body": task.to_issue_body(),
}
if dry_run:
print(f" [DRY RUN] Would create issue: Task #{task.number}")
return True
try:
response = requests.post(url, headers=headers, data=json.dumps(data))
response.raise_for_status()
issue = response.json()
# Add labels
label_url = f"{GITEA_URL}/api/v1/repos/{REPO_OWNER}/{REPO_NAME}/issues/{issue['number']}/labels"
label_data = {"labels": task.get_label_ids()}
label_response = requests.put(label_url, headers=headers, data=json.dumps(label_data))
if label_response.status_code == 200:
print(f" ✅ Created issue #{issue['number']}: Task #{task.number} - {task.title}")
return True
else:
print(f" ⚠️ Created issue #{issue['number']} but failed to add labels")
return True
except Exception as e:
print(f" ❌ Failed to create issue for Task #{task.number}: {e}")
return False
def sync_tasks_to_issues(dry_run: bool = False, force: bool = False):
"""Main synchronization function"""
print("🔥❄️ Firefrost Gaming - Task to Issue Sync\n")
# Parse tasks from tasks.md
tasks = parse_tasks_file()
if not tasks:
print("❌ No tasks found")
return
# Get existing issues
existing_issues = get_existing_issues()
# Find tasks that need issues created
missing_tasks = [task for task in tasks if task.number not in existing_issues]
existing_tasks = [task for task in tasks if task.number in existing_issues]
print(f"\n📊 Status:")
print(f" - Total tasks: {len(tasks)}")
print(f" - Already have issues: {len(existing_tasks)}")
print(f" - Need issues created: {len(missing_tasks)}")
if not missing_tasks:
print("\n✅ All tasks already have Gitea issues!")
return
# Create missing issues
print(f"\n🚀 Creating {len(missing_tasks)} missing issues...\n")
created = 0
failed = 0
for task in missing_tasks:
if create_issue(task, dry_run):
created += 1
else:
failed += 1
print(f"\n{'='*60}")
print(f"✅ Successfully created {created} issues")
if failed:
print(f"❌ Failed to create {failed} issues")
print(f"{'='*60}")
if not dry_run:
print("\n💡 Next steps:")
print(" 1. Issues created with status/backlog label")
print(" 2. Manually add issues to 'Firefrost Operations' project board via web UI")
print(" 3. Or wait for project board automation (future enhancement)")
def main():
parser = argparse.ArgumentParser(
description="Sync tasks from docs/core/tasks.md to Gitea issues"
)
parser.add_argument(
'--dry-run',
action='store_true',
help="Show what would be created without actually creating"
)
parser.add_argument(
'--force',
action='store_true',
help="Force update of existing issues (not implemented yet)"
)
args = parser.parse_args()
sync_tasks_to_issues(dry_run=args.dry_run, force=args.force)
if __name__ == "__main__":
main()