# 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
```