154 lines
3.7 KiB
Markdown
154 lines
3.7 KiB
Markdown
# LinearGiteaIntegration
|
|
|
|
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
|
|
``` |