initial ai implementation

2026-04-20 14:48:33 +02:00
parent f91eaed663
commit 05c4b4b04c
31 changed files with 1420 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,154 @@
 # LinearGiteaIntegration

-Integrate Linear into gitea 
+Integrate Linear issue tracking with Gitea - similar to the Linear-GitHub integration.
+
+## Features
+
+- **PR Linking**: Automatically link pull requests to Linear issues by including the issue ID (e.g., `LIN-123`) in branch names, PR titles, or descriptions
+- **Workflow Automation**: Automatically update Linear issue status based on PR state changes (opened → In Progress, merged → Done, closed → Todo)
+- **Issues Sync**: Synchronize issues between Gitea and Linear (one-way or two-way)
+- **Commit Linking**: Link commits to Linear issues by including issue IDs in commit messages
+- **Branch Suggestions**: Get suggested branch names for Linear issues via API
+
+## Requirements
+
+- Python 3.10+
+- Linear API key
+- Gitea instance with API token
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+Or with uv:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+1. Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `config.yaml` to configure your settings:
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+linear:
+  api_key: "your-linear-api-key"
+  webhook_secret: "your-linear-webhook-secret"
+
+gitea:
+  url: "https://gitea.yourdomain.com"
+  token: "your-gitea-token"
+  webhook_secret: "your-gitea-webhook-secret"
+
+sync:
+  enabled_repos:
+    - "your-org/your-repo"
+  default_team_id: "your-linear-team-id"
+  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
+```
+
+3. Set environment variables in `.env`:
+
+```
+LINEAR_API_KEY=lin_xxx
+GITEA_URL=https://gitea.yourdomain.com
+GITEA_TOKEN=gitea_token_xxx
+CONFIG_PATH=config.yaml
+```
+
+### Getting API Keys
+
+**Linear API Key:**
+1. Go to Linear workspace Settings > API
+2. Create a new API key
+
+**Gitea Token:**
+1. Go to Settings > Applications > Generate a new token
+2. Requires `repo` and `write:issue` scopes
+
+## Running the Server
+
+```bash
+# Development
+python -m linear_gitea_integration
+
+# Or with uvicorn
+uvicorn linear_gitea_integration.main:app --reload
+```
+
+The server will start on `http://0.0.0.0:8080` by default.
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Health check |
+| `/api/issues/{issue_id}/branch` | GET | Get branch suggestion for issue |
+| `/api/sync/issue` | POST | Manually sync issue to Gitea |
+| `/webhooks/gitea` | POST | Gitea webhook endpoint |
+| `/webhooks/linear` | POST | Linear webhook endpoint |
+
+## Setting Up Webhooks
+
+### Gitea Webhook
+
+1. Go to your repository Settings > Webhooks
+2. Add a new webhook:
+   - **URL**: `https://your-server.com/webhooks/gitea`
+   - **Secret**: Use the value from `gitea.webhook_secret`
+   - **Trigger**: Select events: Push, Pull Request, Issues
+
+### Linear Webhook
+
+1. Go to Linear workspace Settings > Webhooks
+2. Add a new webhook:
+   - **URL**: `https://your-server.com/webhooks/linear`
+   - **Secret**: Use the value from `linear.webhook_secret`
+   - **Events**: Issues (create, update)
+
+## Development
+
+Run tests:
+
+```bash
+PYTHONPATH=src pytest tests/
+```
+
+Project structure:
+
+```
+LinearGiteaIntegration/
+├── src/linear_gitea_integration/
+│   ├── api/           # REST API routes
+│   ├── config.py      # Configuration management
+│   ├── models.py      # Pydantic models
+│   ├── services/      # API clients
+│   ├── webhooks/      # Webhook handlers
+│   └── main.py        # Application entry point
+├── tests/             # Unit tests
+├── config.yaml        # Configuration file
+└── .env.example       # Environment variables template
+```