Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/paperdiamond/gitlin

AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits. Just comment /create-issues and let Claude do the work.
https://github.com/paperdiamond/gitlin

ai automation claude developer-tools github-bot linear productivity project-management

Last synced: 4 months ago
JSON representation

AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits. Just comment /create-issues and let Claude do the work.

Awesome Lists containing this project

README 

          
# gitlin 🤖



> AI-powered GitHub bot that creates Linear issues from code reviews, PRs, and commits.



Stop manually copying tasks from code reviews into Linear. Just comment `/create-issues` and let Claude do the work.



## Features



- ✨ **AI-Powered Extraction** - Uses Claude to intelligently parse comments, reviews, and PRs

- 📋 **Smart Issue Creation** - Automatically populates title, description, priority, effort, labels, and assignees

- 🔗 **Dependency Management** - Links related issues automatically

- 👀 **Visual Feedback** - Emoji reactions show processing status (eyes → rocket on success)

- ⚡ **Zero Configuration** - Works out of the box with sensible defaults

- 🎯 **Context-Aware** - Understands PR context, commit history, and review feedback

- 🔐 **Secure** - Auto-fetches Linear team UUID, validates origins, minimal permissions

- 🚀 **Fast** - Docker-based execution with 87% faster cold start (19s vs 152s)

- 🎯 **Smart Filtering** - Automatically skips resolved comment threads to prevent duplicates

- 🏷️ **Intelligent Labels** - AI receives Linear's available labels for accurate suggestions, automatic tagging

- 🔄 **Duplicate Detection** - Tracks processed comments to prevent creating duplicate issues on multiple runs

- 🔍 **Automatic Comment Gathering** - Fetches and analyzes all unresolved PR comments in one operation

- 🖥️ **Interactive TUI** - Terminal interface for browsing, selecting, and editing issues before creation



## Quick Start



### Option 1: Automatic Setup (Recommended)



Clone this repo into your project and run the interactive setup:



```zsh

cd your-project

git clone https://github.com/paperdiamond/gitlin.git .gitlin

cd .gitlin

pnpm install

pnpm run setup

```



The setup wizard will:

- Install the GitHub Action workflow

- Automatically fetch your Linear teams and let you select one (no manual UUID lookup!)

- Add required secrets to your repository (via GitHub CLI)

- Verify everything is configured correctly



### Option 2: Manual Setup



If you prefer to set things up manually:



**1. Add the GitHub Action workflow**



Create `.github/workflows/gitlin.yml`:



```yaml

name: Gitlin - Create Linear Issues

on:

  issue_comment:

    types: [created]

  pull_request_review_comment:

    types: [created]



jobs:

  create-issues:

    if: contains(github.event.comment.body, '/create-issues')

    uses: paperdiamond/gitlin/.github/workflows/gitlin-bot.yml@main

    secrets:

      LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}

      LINEAR_TEAM_ID: ${{ secrets.LINEAR_TEAM_ID }}

      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

```



**2. Add Secrets**



Go to your repository's Settings → Secrets → Actions and add:



- `LINEAR_API_KEY` - Get from https://linear.app/settings/api

- `LINEAR_TEAM_ID` - Your Linear team UUID (get it by running `node scripts/get-team-id.js` in the gitlin directory)

- `ANTHROPIC_API_KEY` - Get from https://console.anthropic.com/



### Interactive TUI Mode



For a more hands-on experience, use the interactive Terminal User Interface:



```zsh

cd .gitlin

pnpm tui

```



**Requirements:** The TUI requires a `.env` file with your API keys:

```zsh

cp .env.example .env

# Edit .env and add your LINEAR_API_KEY, LINEAR_TEAM_ID, and ANTHROPIC_API_KEY

```



#### TUI Workflow



1. **Select Repository** - Auto-detects current repo from git, or choose from your recent GitHub repos

2. **Select PR** - Browse open PRs or enter a PR number manually

3. **Select Comments** - View all unresolved comments, with existing Linear tickets marked (🎫)

4. **AI Analysis** - Claude parses selected comments and extracts actionable issues

5. **Review & Edit** - Toggle issues on/off, edit title/description/priority/effort/labels

6. **Confirm & Create** - Preview final issues before creating them in Linear

7. **Results** - See created issues with direct links to Linear



#### TUI Features



- 📂 **Smart Repo Detection** - Auto-detects current repo from git remote

- 📋 **PR Browser** - Lists open PRs with author info, or enter PR # manually

- 🎫 **Duplicate Detection** - Comments with existing Linear tickets are marked

- ✏️ **Full Issue Editor** - Edit all fields: title, description, priority, effort, labels

- 🏷️ **Label Picker** - Multi-select from your Linear team's available labels

- ☑️ **Selective Creation** - Toggle individual issues on/off before creating



#### Keyboard Shortcuts



| Screen | Key | Action |

|--------|-----|--------|

| All | `↑/↓` or `j/k` | Navigate up/down |

| All | `Esc` | Go back to previous screen |

| All | `q` | Quit (except when editing) |

| All | `Ctrl+C` | Force quit |

| Comments | `Space` | Toggle comment selection |

| Comments | `a` | Select all comments |

| Comments | `n` | Deselect all comments |

| Comments | `Enter` | Continue to AI analysis |

| Issues | `Space` or `t` | Toggle issue enabled/disabled |

| Issues | `Enter` or `e` | Edit selected issue |

| Issues | `c` | Continue to confirmation |

| Editor | `Enter` or `e` | Edit current field |

| Editor | `s` | Save and return |

| Results | `r` | Create more issues (restart) |

| Error | `r` | Retry from beginning |



### Use It (GitHub Action)



Comment `/create-issues` on any PR or issue, and the bot will:

1. **Automatically fetch all unresolved comments** on the PR (both issue comments and review comments)

2. **Filter out resolved review threads** to prevent duplicate issues

3. Parse all comments and extract actionable items using AI

4. Create Linear issues with full details

5. Reply with links to the created issues



**Note:** On PRs, the bot analyzes ALL unresolved comments, not just the one containing `/create-issues`. This means you can add multiple comments throughout a code review, then trigger issue creation with a single `/create-issues` command.



## Examples



### From Code Review Feedback



**GitHub Comment:**

```

Great work on the feature! A few things to address:



1. Add input validation for user email addresses

2. Extract the authentication logic into a reusable service

3. Consider adding rate limiting to the API endpoints



The security changes look good though!



/create-issues

```



**gitlin creates:**

```

✅ Created 3 Linear issues:



- [PROJ-123](https://linear.app/team/issue/PROJ-123) Add input validation for user email addresses

  Priority: High | Effort: Small | Assignee: alex@company.com



- [PROJ-124](https://linear.app/team/issue/PROJ-124) Extract authentication logic into reusable service

  Priority: Medium | Effort: Medium | Assignee: taylor@company.com



- [PROJ-125](https://linear.app/team/issue/PROJ-125) Add rate limiting to API endpoints

  Priority: Low | Effort: Large | Assignee: Unassigned

```



### From Commit Messages



The bot can also parse commit messages with follow-up items:



```

feat: Add user authentication with OAuth



## Follow-up Items



1. Add comprehensive error handling for auth failures (High priority, 3 points, jordan@company.com)

   - Display user-friendly error messages for common auth failures

   - Log authentication errors to monitoring service

   - Add retry mechanism for transient failures



2. Implement session refresh token rotation (Medium priority, 5 points, casey@company.com)

   - Automatically refresh access tokens before expiration

   - Handle refresh token expiration gracefully

   - Add security audit logging for token refresh events



3. Add multi-factor authentication support (Low priority, 8 points, Unassigned)

   - Research MFA provider options (Authy, Google Authenticator)

   - Design user enrollment flow

   - Implement backup codes for account recovery



/create-issues

```



## How It Works



```mermaid

graph LR

    A[Comment on GitHub] --> B[Trigger GitHub Action]

    B --> C[Extract Context]

    C --> D[AI Parser Claude]

    D --> E[Create Linear Issues]

    E --> F[Post Results]

```



1. **Trigger**: User comments `/create-issues`

2. **Fetch**: Bot automatically fetches all unresolved comments on the PR

3. **Filter**: Resolved review comment threads are skipped

4. **Context**: Bot gathers PR title, description, and all comment text

5. **AI Parse**: Claude analyzes content and extracts structured issues

6. **Validation**: Zod validates the parsed data structure

7. **Creation**: Linear SDK creates issues with all fields

8. **Response**: Bot replies with links to created issues



## Configuration



Create `.github/gitlin.json` to customize behavior:



```json

{

  "defaultPriority": "medium",

  "labelMapping": {

    "security": ["security", "vulnerability"],

    "performance": ["performance", "optimization"],

    "ui": ["frontend", "design"]

  },

  "effortMapping": {

    "small": 1,

    "medium": 3,

    "large": 5

  },

  "gitlinAutoTag": "gitlin-created",

  "skipResolvedComments": true

}

```



### Configuration Options



- **`labelMapping`**: Map AI-suggested labels to multiple Linear labels

- **`gitlinAutoTag`**: Custom tag added to all created issues (default: `"gitlin-created"`)

- **`skipResolvedComments`**: Skip creating issues from resolved comment threads (default: `true`)

- **`defaultPriority`**: Default priority if AI can't determine it

- **`effortMapping`**: Map effort estimates to Linear points



## Development



### Setup



```zsh

git clone https://github.com/yourusername/gitlin.git

cd gitlin

pnpm install

cp .env.example .env  # Add your API keys

```



### Run Locally



```zsh

pnpm run dev

```



### Test



```zsh

pnpm test              # Run tests once

pnpm test:watch        # Run tests in watch mode

pnpm lint              # Check for lint errors

pnpm format:check      # Check formatting

```



**CI/CD:** All PRs run automated tests via GitHub Actions. Tests must pass before merging.



### Build



```zsh

pnpm run build

```



## API



### Programmatic Usage



```typescript

import { Gitlin } from "gitlin";



const bot = new Gitlin({

  linearApiKey: "lin_api_...",

  linearTeamId: "abc123",

  anthropicApiKey: "sk-ant-...",

  githubToken: "ghp_...",

});



const result = await bot.processComment({

  owner: "acme",

  repo: "project",

  prNumber: 42,

  commentBody: "Add error handling\n\n/create-issues",

});



console.log(result);

// ✅ Created 1 Linear issue:

// - [ACME-123](https://linear.app/...) Add error handling

```



## Performance



gitlin is optimized for speed and efficiency:



- **87% faster execution**: Docker-based deployment reduces cold start from ~152s to ~19s

- **Smart caching**: Linear labels cached across issue creation runs

- **Efficient AI calls**: Claude receives only relevant context for faster responses

- **Duplicate detection**: Skips already-processed comments to save time and API calls



### Before vs After

```

Before (pnpm install):  ~152s  (install 90s + build 30s + run 32s)

After (Docker):         ~19s   (pull 3s + run 16s, cached)

```



## Cost



gitlin uses Claude Sonnet which costs approximately:

- **$0.01-0.05 per run** (depending on context size)

- Average PR review: ~$0.02

- 500 uses/month: ~$10



This pays for itself immediately by saving 5-10 minutes per code review.



## Roadmap



### Completed ✅

- [x] Docker-based execution for 87% faster performance (19s vs 152s)

- [x] Automatic resolution filtering (skip resolved comments)

- [x] Intelligent label suggestions (AI receives Linear labels)

- [x] Label mapping configuration

- [x] Auto-tagging for audit trail (gitlin-created tag)

- [x] Duplicate detection (tracks processed comments)

- [x] Automatic comment gathering (fetches all unresolved PR comments)

- [x] Conservative priority assignment (prevents over-prioritization)

- [x] Interactive TUI for manual issue selection



### Planned

- [ ] Sub-issue hierarchy support

- [ ] Support for multiple Linear teams

- [ ] Slack integration

- [ ] Custom AI models (GPT-4, local models)

- [ ] Integration with GitHub Projects



## Contributing



Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.



## License



MIT © Paper Diamond



---



**Built with** ❤️ **by Paper Diamond**