Linear ローカル開発ループ

概要

Linear インテグレーション用の効率的なローカル開発ワークフローを構築します。

前提条件

• Node.js 18 以上と TypeScript
• Linear SDK がインストール済み
• 開発用の独立した Linear ワークスペース（推奨）
• ngrok またはこれに類するツール（Webhook テスト用）

手順

Step 1: プロジェクトセットアップ

# プロジェクトを初期化
mkdir linear-integration && cd linear-integration
npm init -y
npm install @linear/sdk typescript ts-node dotenv
npm install -D @types/node vitest

# tsconfig.json を作成
npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext

Step 2: 環境構成

# ローカル開発用の .env を作成
cat > .env << 'EOF'
LINEAR_API_KEY=lin_api_dev_xxxxxxxxxxxx
LINEAR_WEBHOOK_SECRET=your_webhook_secret
NODE_ENV=development
EOF

# .env.example を作成（こちらをコミット）
cat > .env.example << 'EOF'
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
LINEAR_WEBHOOK_SECRET=
NODE_ENV=development
EOF

# .gitignore に追加
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

Step 3: 開発用クライアントの作成

// src/client.ts
import { LinearClient } from "@linear/sdk";
import dotenv from "dotenv";

dotenv.config();

export const linearClient = new LinearClient({
  apiKey: process.env.LINEAR_API_KEY!,
});

export async function verifyClient(): Promise<boolean> {
  try {
    const viewer = await linearClient.viewer;
    console.log(`[Linear] Connected as ${viewer.name}`);
    return true;
  } catch (error) {
    console.error("[Linear] Connection failed:", error);
    return false;
  }
}

Step 4: テスト用ユーティリティの作成

// src/test-utils.ts
import { linearClient } from "./client";

export async function createTestIssue(teamKey: string) {
  const teams = await linearClient.teams();
  const team = teams.nodes.find(t => t.key === teamKey);

  if (!team) throw new Error(`Team ${teamKey} not found`);

  const result = await linearClient.createIssue({
    teamId: team.id,
    title: `[TEST] ${new Date().toISOString()}`,
    description: "Automated test issue - safe to delete",
  });

  return result.issue;
}

export async function cleanupTestIssues(teamKey: string) {
  const issues = await linearClient.issues({
    filter: {
      team: { key: { eq: teamKey } },
      title: { startsWith: "[TEST]" },
    },
  });

  for (const issue of issues.nodes) {
    await issue.delete();
  }

  console.log(`Cleaned up ${issues.nodes.length} test issues`);
}

Step 5: ウォッチモードの設定

// package.json scripts
{
  "scripts": {
    "dev": "ts-node --watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "verify": "ts-node src/verify.ts"
  }
}

出力

• ローカル開発環境が準備完了
• 環境変数が構成済み
• テストデータを作成・削除するためのテスト用ユーティリティ
• 高速な反復開発のためのウォッチモード

エラーハンドリング

エラー	原因	解決方法
API key not set	.env ファイルが見つからない	.env.example を .env にコピーする
Cannot find module	TypeScript の設定に問題がある	tsconfig.json のパスを確認する
Connection refused	ネットワークの問題	インターネット接続を確認する
Webhook not received	トンネルが実行されていない	ngrok トンネルを起動する

例

ngrok を使用した Webhook 開発

# ターミナル 1: Webhook サーバーを起動
npm run dev

# ターミナル 2: ngrok トンネルを起動
ngrok http 3000

# https URL をコピーして Linear の Webhook 設定に追加

インテグレーションテストの例

// tests/integration.test.ts
import { describe, it, expect, afterAll } from "vitest";
import { createTestIssue, cleanupTestIssues } from "../src/test-utils";

describe("Linear Integration", () => {
  const teamKey = "ENG"; // テストチーム

  afterAll(async () => {
    await cleanupTestIssues(teamKey);
  });

  it("should create and fetch an issue", async () => {
    const issue = await createTestIssue(teamKey);
    expect(issue).toBeDefined();
    expect(issue?.title).toContain("[TEST]");
  });
});

リソース

• Linear SDK TypeScript
• Webhook 開発
• ngrok ドキュメント

次のステップ

ローカル開発のセットアップ後は、ベストプラクティスについて linear-sdk-patterns を参照してください。