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

pip install -r requirements.txt

Or with uv:

uv sync

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit config.yaml to configure your settings:

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

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

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