LinearGiteaIntegration/SPEC.md

LinearGiteaIntegration Specification

Project Overview

• Project Name: LinearGiteaIntegration
• Type: Web service / Integration middleware
• Core Functionality: Integrate Linear issue tracking with Gitea, enabling PR/commit linking, workflow automation, and bidirectional issue sync
• Target Users: Development teams using Linear for issue tracking and Gitea for Git hosting

Architecture

Components

1. Webhook Server: Receives events from Gitea (push, pull request, issues)
2. Linear API Client: Communicates with Linear API to create/update issues
3. Gitea API Client: Communicates with Gitea API to create branches, PRs, update issues
4. Configuration Manager: Handles API keys, webhooks, and settings

Technology Stack

• Language: Python
• Web Framework: FastAPI (modern, async Python web framework)
• Configuration: YAML-based config file + environment variables

Functionality Specification

1. PR Linking

• Detect Linear issue ID (e.g., LIN-123) in:
  • Branch name
  • PR title
  • PR description
• When PR is opened/linked, add PR link to Linear issue
• Support magic words: "closes", "fixes", "resolves" + issue ID

2. Workflow Automation

• Map Gitea PR states to Linear issue statuses:
  • PR created → Move issue to "In Progress"
  • PR merged → Move issue to "Done"
  • PR closed (not merged) → Move issue back to "Todo"
• Configurable status mappings per team

3. Issues Sync

• One-way sync: Gitea issues → Linear issues
• Two-way sync: Changes sync both ways
• Sync properties: title, description, status, assignee, labels, comments
• Configurable per-repository settings

4. Commit Linking

• Detect Linear issue ID in commit messages
• Add commit reference to Linear issue
• Support multiple issues per commit

5. Branch Suggestions

• API endpoint to get suggested branch name for a Linear issue
• Format: {issue-id}-{slugified-title} (e.g., LIN-123-add-login-feature)

Configuration

server:
  host: "0.0.0.0"
  port: 8080

linear:
  api_key: "${LINEAR_API_KEY}"
  webhook_secret: "${LINEAR_WEBHOOK_SECRET}"

gitea:
  url: "https://gitea.example.com"
  token: "${GITEA_TOKEN}"
  webhook_secret: "${GITEA_WEBHOOK_SECRET}"

sync:
  enabled_repos:
    - "my-org/my-repo"
  default_team_id: "team_xxx"
  status_mappings:
    pr_created: "In Progress"
    pr_merged: "Done"
    pr_closed: "Todo"
  sync_direction: "one-way"  # or "two-way"

features:
  pr_linking: true
  workflow_automation: true
  issues_sync: true
  commit_linking: true
  branch_suggestions: true

API Endpoints

Webhooks

• POST /webhooks/gitea - Receive Gitea events
• POST /webhooks/linear - Receive Linear events

REST API

• GET /api/health - Health check
• GET /api/issues/:id/branch - Get suggested branch name for issue
• POST /api/sync/issue - Manually trigger issue sync

Webhook Events to Handle

Gitea Events

• push - Parse commit messages for issue IDs
• pull_request - Link PRs, update status
• issues - Sync issues to Linear

Linear Events

• Issue - Sync issue changes to Gitea (for two-way sync)

Acceptance Criteria

1. Server starts and listens on configured port
2. Gitea webhook endpoint accepts and processes events
3. PR linking works when issue ID found in branch/PR title
4. Issue status updates based on PR state changes
5. Issues created in Gitea appear in Linear (when sync enabled)
6. Branch suggestion endpoint returns proper format
7. Configuration loads from YAML file and environment variables
8. Unit tests cover core functionality