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:**
```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** 💙🔥❄️