# Task #48 — Gitea/Plane Integration via n8n

**Status:** READY — pending n8n rebuild (Task #34)
**Priority:** Tier 2 — Major Infrastructure
**Time:** 2-3 hours
**Created:** March 15, 2026
**Created By:** Chronicler #31
**Owner:** Michael "Frostystyle" Krause
**Depends:** Task #34 (n8n rebuild from scratch)

---

## The Goal

Hands-off, automated two-way sync between Gitea (source of truth for docs/code)
and Plane (task tracking for Meg, Holly, and all staff). Neither Meg nor Holly
should need to manually cross-reference between systems.

---

## Why n8n (Not Native Integration)

Plane has no native Gitea integration. GitHub/GitLab integrations exist but
are likely Pro features and don't apply to our self-hosted Gitea.

n8n is already in the Firefrost stack on TX1. It's purpose-built for exactly
this kind of cross-platform automation. Once n8n is rebuilt (Task #34), this
integration is straightforward.

---

## Workflow Design

### Gitea → Plane (commit updates task)

1. Developer pushes commit with Plane issue ID in message (e.g. `INFRA-42`)
2. Gitea fires webhook to n8n
3. n8n parses commit message for issue ID
4. n8n calls Plane API to:
   - Add comment: "Commit: [message] by [author]"
   - Optionally update issue status (e.g. "In Progress" → "Done" on keyword)

**Trigger keywords in commit messages:**
- `closes INFRA-42` → mark issue Done
- `refs INFRA-42` → add comment only
- `fixes INFRA-42` → mark issue Done

### Plane → Gitea (task creation creates issue)

1. New Plane issue created in Infrastructure project
2. Plane fires webhook to n8n
3. n8n creates matching Gitea issue in ops manual repo
4. Links back to Plane issue URL in Gitea issue body

---

## Technical Requirements

### Plane API
- Generate API token: Workspace Settings → Access Tokens
- Base URL: `https://tasks.firefrostgaming.com/api/v1/`
- Docs: https://developers.plane.so/api-reference/introduction

### Gitea Webhook
- Token: `3c40388246ae816fe21cdca26fce4e1c66989dd1` (in Vaultwarden)
- Webhook URL: `http://[n8n-url]/webhook/gitea-plane`
- Events: Push, Issues

### Gitea Allowed Webhooks
Gitea restricts webhook destinations. Need to add n8n URL to allowed list
in Gitea's app.ini:
```
[webhook]
ALLOWED_HOST_LIST = n8n.firefrostgaming.com
```

### n8n Workflows to Build
1. **Gitea Push → Plane** — parse commit, update issue
2. **Plane Issue → Gitea** — create tracking issue

---

## Implementation Order

1. Complete Task #34 (n8n rebuild) first
2. Generate Plane API token
3. Update Gitea app.ini with n8n in allowed webhook hosts
4. Build n8n workflow: Gitea Push → Plane issue update
5. Build n8n workflow: Plane issue → Gitea issue
6. Test with a real commit referencing a Plane issue
7. Document commit message convention for team

---

## Commit Message Convention (for team)

Once live, all commits should reference Plane issue IDs:

```
feat: add LuckPerms builder rank

Implements Builder rank with WorldEdit permissions.
closes BUILDS-12
refs INFRA-7
```

Michael to document this in a team guide once integration is live.

---

## Related Tasks
- Task #34 — n8n Rebuild (prerequisite)
- Task #47 — Plane Deployment (complete)
- Task #11 — Mailcow (complete)

---

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