119 lines
3.5 KiB
Markdown
119 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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 |