firefrost-operations-manual/docs/procedures/gitea-project-management-setup.md

# Gitea-Native Project Management — Setup Guide

**Created:** March 19, 2026  
**Purpose:** Single source of truth for all Firefrost Gaming task management  
**Philosophy:** If it's not a Gitea Issue, it doesn't exist

---

## Phase 1: ✅ Global Label Schema (COMPLETE)

**Status:** All 34 labels created in `firefrost-operations-manual` repository

### Label Categories Created:

**STATUS Labels** (Scoped — only one can be applied):
- `status/backlog` — Not yet started, in backlog
- `status/to-do` — Ready to start, in queue
- `status/in-progress` — Currently being worked on
- `status/review` — Work complete, awaiting review
- `status/blocked` — Cannot proceed, blocked by dependency
- `status/done` — Completed and closed

**PRIORITY Labels** (Scoped):
- `priority/critical` — Emergency, immediate attention
- `priority/high` — Important, address soon
- `priority/medium` — Normal priority
- `priority/low` — Nice to have, not urgent

**TYPE Labels** (Scoped):
- `type/bug` — Something isn't working
- `type/feature` — New feature or enhancement
- `type/task` — General task or work item
- `type/docs` — Documentation improvements
- `type/infrastructure` — Infrastructure/deployment/DevOps
- `type/refactor` — Code refactoring or technical debt

**AREA Labels** (Non-scoped — multiple can be applied):
- `area/panel` — Pterodactyl Panel
- `area/wings` — Pterodactyl Wings
- `area/billing` — Paymenter billing system
- `area/email` — Mailcow email system
- `area/website` — Ghost CMS website
- `area/automation` — n8n workflows and automation
- `area/networking` — Network infrastructure
- `area/game-servers` — Minecraft or other game servers
- `area/operations` — General operations and documentation

**ASSIGNMENT Labels** (Non-scoped):
- `for/holly` — Assigned to Holly (unicorn20089)
- `for/meg` — Assigned to Meg (GingerFury)
- `for/michael` — Assigned to Michael (Frostystyle)

**SPECIAL Labels** (Non-scoped):
- `help-wanted` — Extra attention needed
- `good-first-issue` — Good for newcomers
- `wont-do` — This will not be worked on

### To View Labels:

1. Go to: https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual
2. Click "Labels" in the navigation
3. You'll see all 34 labels with colors and descriptions

---

## Phase 2: Create Organization-Level Project (MANUAL SETUP REQUIRED)

**Note:** Gitea's Project API is not fully available in v1.21.5, so this must be done via web UI.

### Step-by-Step:

**1. Navigate to Organization**
- Go to: https://git.firefrostgaming.com/firefrost-gaming
- Click "Projects" tab at the top

**2. Create New Project**
- Click "New Project" button (green, top right)
- Fill in details:
  - **Title:** `Firefrost Operations`
  - **Description:** `Organization-wide task management for Firefrost Gaming infrastructure, operations, and development`
  - **Template:** Select "Basic Kanban"
  - **Card Previews:** Leave as default or select "Images and Text"

**3. Click "Create Project"**

**4. Customize Kanban Columns**

Default columns may be generic. You can rename/add columns:
- Click on a column name to rename
- Click "New Column" to add more

**Recommended Columns:**
1. **Backlog** — Tasks not yet ready to start
2. **To Do** — Ready to work on, prioritized
3. **In Progress** — Currently being worked on
4. **Review** — Awaiting review or approval
5. **Done** — Completed tasks

---

## Phase 3: Create Issues and Add to Project

### Creating an Issue:

**Method 1: Via Web UI**

1. Go to any repository (e.g., operations manual)
2. Click "Issues" tab
3. Click "New Issue"
4. Fill in:
   - **Title:** Clear, actionable title
   - **Description:** Detailed explanation (use Markdown)
   - **Labels:** Select appropriate labels (status, priority, type, area)
   - **Projects:** Select "Firefrost Operations"
   - **Assignees:** Assign to yourself, Holly, or Meg
   - **Milestone:** (optional, for grouping related tasks)
5. Click "Create Issue"

**Method 2: Via Gitea CLI (`tea`)**

```bash
# Install tea CLI first (if not already installed)
# Linux/Mac:
# Download from: https://gitea.com/gitea/tea/releases

# Configure tea
tea login add \
  --name firefrost \
  --url https://git.firefrostgaming.com \
  --token e0e330cba1749b01ab505093a160e4423ebbbe36

# Create an issue
tea issues create \
  --repo firefrost-gaming/firefrost-operations-manual \
  --title "Deploy ATM10 To The Sky server" \
  --body "Deploy new skyblock server as part of soft launch prep" \
  --labels "type/task,priority/high,area/game-servers,status/to-do,for/michael"
```

### Moving Issues on Kanban Board:

1. Go to: https://git.firefrostgaming.com/org/firefrost-gaming/projects
2. Click on "Firefrost Operations" project
3. You'll see the Kanban board
4. Drag and drop issue cards between columns
5. As you move cards, you can manually update their `status/*` label to match

---

## Phase 4: Issue Templates (YAML)

Create standardized issue templates to make creating issues faster and more consistent.

### Step-by-Step:

**1. Create `.gitea/ISSUE_TEMPLATE/` directory in your repository**

```bash
cd /firefrost-operations-manual
mkdir -p .gitea/ISSUE_TEMPLATE
```

**2. Create Bug Report Template**

```bash
cat > .gitea/ISSUE_TEMPLATE/bug_report.yaml << 'EOF'
name: Bug Report
about: Report a bug or issue
labels:
  - type/bug
  - status/to-do
body:
  - type: markdown
    attributes:
      value: |
        ## Bug Report
        Please provide as much detail as possible.
  
  - type: input
    id: summary
    attributes:
      label: Summary
      description: A brief summary of the bug
      placeholder: "e.g., Mailcow cannot send emails"
    validations:
      required: true
  
  - type: textarea
    id: description
    attributes:
      label: Description
      description: Detailed description of the bug
      placeholder: "What happened? What did you expect to happen?"
    validations:
      required: true
  
  - type: textarea
    id: steps
    attributes:
      label: Steps to Reproduce
      description: How can we reproduce this bug?
      placeholder: |
        1. Go to...
        2. Click on...
        3. See error...
    validations:
      required: true
  
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options:
        - Low
        - Medium
        - High
        - Critical
    validations:
      required: true
  
  - type: dropdown
    id: area
    attributes:
      label: Area
      options:
        - Panel
        - Wings
        - Billing
        - Email
        - Website
        - Automation
        - Networking
        - Game Servers
        - Operations
    validations:
      required: true
EOF
```

**3. Create Task Template**

```bash
cat > .gitea/ISSUE_TEMPLATE/task.yaml << 'EOF'
name: Task
about: General task or work item
labels:
  - type/task
  - status/to-do
body:
  - type: markdown
    attributes:
      value: |
        ## Task
        Create a new task for the Firefrost Gaming project.
  
  - type: input
    id: title
    attributes:
      label: Task Title
      description: Clear, actionable title
      placeholder: "e.g., Deploy ATM10 Sky server"
    validations:
      required: true
  
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What needs to be done?
      placeholder: "Detailed description of the task..."
    validations:
      required: true
  
  - type: textarea
    id: acceptance
    attributes:
      label: Acceptance Criteria
      description: How do we know this is complete?
      placeholder: |
        - [ ] Server deployed
        - [ ] Tested and verified
        - [ ] Documentation updated
  
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options:
        - Low
        - Medium
        - High
        - Critical
      default: 1
    validations:
      required: true
EOF
```

**4. Commit and push templates**

```bash
git add .gitea/ISSUE_TEMPLATE/
git commit -m "feat: add issue templates for bug reports and tasks"
git push
```

**5. Test the templates**

1. Go to repository Issues page
2. Click "New Issue"
3. You should now see template options: "Bug Report" and "Task"
4. Select one to create a pre-formatted issue

---

## Phase 5: n8n Automation (Future)

**Purpose:** Automate notifications and maintenance tasks

### Planned Automations:

**1. Discord Notifications**
- New issue created → Discord #dev-notifications
- Issue assigned to you → Discord DM
- Issue status changed → Discord update

**2. Auto-Labeling**
- Issue mentions "bug" → auto-apply `type/bug`
- Issue mentions "urgent" → auto-apply `priority/high`
- Issue mentions specific system → auto-apply `area/*`

**3. Status Reports**
- Weekly summary of open issues
- Monthly progress report
- Burndown tracking

**Implementation:**
- n8n workflow listening to Gitea webhooks
- Parse issue events
- Route to Discord, apply labels, etc.

---

## Workflow Examples

### Example 1: Holly Gets a Task

**Michael creates task:**
1. Go to Issues → New Issue
2. Use "Task" template
3. Title: "Backup 10 retiring servers"
4. Description: (paste from checklist)
5. Labels: `type/task`, `priority/high`, `area/game-servers`, `for/holly`
6. Projects: "Firefrost Operations"
7. Assignees: Holly
8. Create Issue

**Holly works on it:**
1. Goes to Firefrost Operations Kanban
2. Sees issue in "To Do" column
3. Drags to "In Progress"
4. Updates `status/in-progress` label
5. Does the work
6. Comments on issue with progress
7. When done, drags to "Done"
8. Updates `status/done` label
9. Closes issue

### Example 2: Bug Report

**Meg finds a bug:**
1. Issues → New Issue → "Bug Report" template
2. Fills in form (summary, description, steps, priority, area)
3. Creates issue
4. Michael sees it in Kanban "To Do" column
5. Assigns to himself
6. Moves to "In Progress"
7. Fixes bug
8. Commits with reference: `git commit -m "fix: mailcow SMTP issue (closes #123)"`
9. Issue auto-closes when commit is pushed

### Example 3: Feature Request

**Michael plans new feature:**
1. Creates issue with `type/feature` label
2. Assigns `status/backlog` (not ready yet)
3. Adds to Kanban "Backlog" column
4. When ready to start, moves to "To Do"
5. Changes status to `status/to-do`
6. Begins work, moves to "In Progress"
7. Finishes, moves to "Review"
8. Holly reviews, approves
9. Moves to "Done", closes issue

---

## Migration from tasks.md

**Current:** `docs/core/tasks.md` has a big list of tasks

**New Approach:**
1. Convert each task to a Gitea Issue
2. Apply appropriate labels
3. Add to "Firefrost Operations" project
4. Archive old tasks.md (keep for reference)

**Migration Script Concept:**

```bash
# Parse tasks.md
# For each task:
#   - Create Gitea issue via API
#   - Apply labels based on task content
#   - Add to project

# Example for one task:
tea issues create \
  --repo firefrost-gaming/firefrost-operations-manual \
  --title "Task #48: Gitea/Plane Integration" \
  --body "Status: WON'T DO - Plane not needed, Gitea has native Kanban" \
  --labels "type/task,status/done,wont-do,area/automation"
```

---

## Benefits of This Approach

✅ **Single Source of Truth**
- All tasks in one place (Gitea)
- No sync complexity
- No Plane middleware

✅ **Visual Management**
- Kanban board for progress tracking
- Drag-and-drop simplicity
- Color-coded labels

✅ **Organization-Wide**
- One board across all repos
- Issues from any repo show up
- Unified view of all work

✅ **Standardization**
- Consistent labels across projects
- Issue templates enforce structure
- Less manual typing (accessibility win!)

✅ **Git Integration**
- Link commits to issues
- Auto-close issues with commit messages
- Full audit trail

✅ **Automation Ready**
- Gitea webhooks available
- n8n can listen and act
- Discord notifications

✅ **No External Dependencies**
- Self-hosted
- No third-party services
- Data sovereignty

---

## Next Actions

**Immediate (Manual Setup):**
1. [ ] Create "Firefrost Operations" organization project via web UI
2. [ ] Set up Kanban columns (Backlog, To Do, In Progress, Review, Done)
3. [ ] Create a test issue and add it to the project
4. [ ] Verify labels are working
5. [ ] Create issue templates in operations manual repo

**Short Term:**
1. [ ] Migrate existing tasks from tasks.md to Gitea Issues
2. [ ] Document workflow for Holly and Meg
3. [ ] Train team on using Kanban board

**Long Term:**
1. [ ] Set up n8n webhooks for Discord notifications
2. [ ] Build auto-labeling automation
3. [ ] Create weekly status report automation
4. [ ] Explore Gitea Actions for CI/CD integration

---

## Resources

- **Gitea Documentation:** https://docs.gitea.com
- **Gitea Projects Guide:** https://blog.gitea.com/introducing-new-features-of-labels-and-projects/
- **Operations Manual:** `git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual`
- **Your Gitea Instance:** https://git.firefrostgaming.com

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️