github-to-linear

A CLI tool to import a single GitHub issue to Linear.

Prerequisites

GitHub CLI

This tool requires GitHub CLI (gh) to be installed and authenticated:

# macOS
brew install gh

# Authenticate
gh auth login

GitHub CLI Installation Guide

Linear API Key

Get your Linear API key from https://linear.app/settings/api

Required Permissions:

• Read (required)
• Create issues (required)
• Create comments (required if using --with-comments)

Quick Start

Import a GitHub issue to Linear using npx (no installation required):

npx github-to-linear import \
  --linear-key lin_api_xxxxxxxxxxxxx \
  --owner octocat \
  --repo hello-world \
  --issue 42 \
  --team ENG

Find Your Team Key

Your team key can be found in the Linear URL when viewing your team:

https://linear.app/your-workspace/team/ENG/...
                                        ^^^
                                     Team Key

For example:

• https://linear.app/acme/team/ENG/active → Team Key is ENG
• https://linear.app/acme/team/PROD/backlog → Team Key is PROD

Simply navigate to your team's page in Linear and copy the team key from the URL.

Usage

Basic Usage

npx github-to-linear import \
  --linear-key YOUR_LINEAR_API_KEY \
  --owner GITHUB_OWNER \
  --repo REPO_NAME \
  --issue ISSUE_NUMBER \
  --team TEAM_KEY

Using Environment Variable

You can also set the Linear API key as an environment variable:

export LINEAR_API_KEY=lin_api_xxxxxxxxxxxxx

npx github-to-linear import \
  --owner octocat \
  --repo hello-world \
  --issue 42 \
  --team ENG

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --owner | -o | GitHub repository owner | Required | | --repo | -r | GitHub repository name | Required | | --issue | -i | GitHub issue number | Required | | --team | -t | Linear team key (e.g., ENG, PROD) | Required | | --linear-key | -k | Linear API key (overrides env var) | - | | --priority | -p | Priority (0-4) | 3 | | --with-comments | - | Import comments as well | false | | --with-labels | - | Import labels as Linear labels | false | | --link-github | - | Link to the original GitHub issue | true | | --yes | -y | Skip confirmation prompt | false |

Priority Values

• 0: No priority
• 1: Urgent
• 2: High
• 3: Medium (default)
• 4: Low

Examples

Simple import

npx github-to-linear import \
  -k lin_api_xxxxxxxxxxxxx \
  -o octocat \
  -r hello-world \
  -i 42 \
  -t ENG

Import with comments and labels

npx github-to-linear import \
  -k lin_api_xxxxxxxxxxxxx \
  -o octocat \
  -r hello-world \
  -i 42 \
  -t ENG \
  --with-comments \
  --with-labels

Skip confirmation (non-interactive)

Useful for CI/CD or scripts:

npx github-to-linear import \
  -k lin_api_xxxxxxxxxxxxx \
  -o octocat \
  -r hello-world \
  -i 42 \
  -t ENG \
  --yes

High priority urgent issue

npx github-to-linear import \
  -k lin_api_xxxxxxxxxxxxx \
  -o octocat \
  -r hello-world \
  -i 42 \
  -t ENG \
  -p 1

Features

• ✅ Import GitHub issue title and body
• ✅ Convert GitHub state to Linear workflow state
  • open → Backlog / Todo
  • closed → Done / Completed
• ✅ Set priority
• ✅ Import labels (auto-create if not exists)
• ✅ Import comments
• ✅ Automatic link to original GitHub issue
• ✅ Interactive confirmation before import
• ✅ Team key resolution (no need for UUID)

Development

Setup

Clone the repository and install dependencies:

git clone <repository-url>
cd github-to-linear
npm install

Build

npm run build

Run in Development Mode

npm run dev -- import -k lin_api_xxx -o owner -r repo -i 123 -t ENG

Lint & Format

This project uses Biome.

# Check
npm run lint

# Auto-fix
npm run lint:fix

# Format
npm run format

License

MIT