課題管理ツールのLinearを、まっさらな状態から触りはじめました。GitHub連携の設定、プロジェクトとIssueの作成、カンバンボードでの作業、そしてコーディングエージェント（OpenAI Codex / Claude Code）のデスクトップアプリと接続するところまでの記録です。
Linearは、Claude CodeやCodexと組み合わせて使うときに、タスクの情報や進捗を置いておく「記憶領域」として相性のよいツールだと感じました。とくに、エージェントに作業させながら進捗や残タスクを管理する（ループエンジニアリング的な）使い方に向いています。GitHubともうまく同期できるので、今のところかなりおすすめできます。
この記事は、上から順に同じ手順を再現できるように書いています。途中で私が引っかかった所には「ここで注意」を入れましたので、同じ失敗をしないための参考にしてみてください。
前提：使ったもの
- OS: Windows 11
- 課題管理: Linear（Web版とデスクトップアプリ）
- リポジトリ: GitHub（題材は個人開発のWindowsアプリ「Promplet」）
- エージェント: Codexアプリ、Claudeアプリ（Claude Code）
GitHubとの連携（アカウント接続）をする場所は、ステップ1で説明します。私はすでに連携済みの状態から始めましたが、未連携でもステップ1で有効化できます。
ステップ0：最初に「GitHub連携の2つの意味」を押さえる
少しだけ概念の話をします。難しく感じるかもしれませんが、実際に手を動かすうちに腑に落ちるので、分からなくても次のステップに進んで構いません。
Linearの「GitHub連携」は、性質の違う2つの機能をまとめてそう呼んでいます。
- コード連携：IssueはLinearで作り、GitHubはコード（ブランチ・PR・コミット）担当。コミットやPRにIssue番号を書くと、Linearのステータスが自動で動く。
- Issue同期：GitHub Issues と Linear Issues を同期する。GitHubに立てたIssueがLinearにもできあがる。
この記事で扱うのは「Issue同期」のほうです。コード連携（コミットやPRでステータスを動かす方）は、この記事では取り扱いません（記事の最後の「ヒント」で簡単に触れます）。
ここで注意 「同期する」という言葉が、この2つのどちらを指すのかで意味が変わります。そして、IssueをGitHubとLinearの両方に二重で作る必要はありません。
ステップ1：GitHubと「連携」する（アカウント接続）
先に言葉を分けておきます。このステップの「連携」はGitHubアカウントをLinearにつなぐこと、次のステップの「同期」はIssueを実際に流すことです。別々の作業なので、分けて進めます。
操作はLinearの画面（Web版）です。
- 左上のチーム名（私の場合はisshiki）の横にある∨（プルダウン）をクリックしてメニューを開き、「Settings」を選ぶ
- 設定画面の左サイドバーにある「Features」グループの中の「Integrations」を開く
- 一覧の「Essentials」の左上にある「GitHub」をクリックする（検索窓で "GitHub" を探してもよい）
4. GitHubの統合画面が開きます。ここの「Enable」を押すとGitHubと連携できます（私はすでに連携済みだったので、この画面では設定項目が並んだ状態でした）
ここで注意 ここでやるのは「アカウントをつなぐ（連携）」だけです。Issueを流す「同期」は次のステップで別に設定します。連携しただけでは、まだIssueは流れてきません。
ステップ2：Issueの「同期」を設定する
連携できたら、同期を設定します。連携済みのGitHub統合画面の下に「GitHub Issues」という項目が出てくるので、その「＋」を押します。
「＋」を押すと、リポジトリとLinearのチームをひも付けるダイアログが開きます。対象リポジトリとチームを選び、片方向（one-way）か双方向（two-way）かを選びます。私は片方向（GitHub→Linear）にしました。
考え方はシンプルです。全員が見える場所（GitHub）に置きたい大きめの項目と、自分の手元で管理したい細かいタスクを、置き場所で分けます。前者をGitHub、後者をLinearに寄せるイメージです。
ここで注意 双方向にすると、Linearに書いた細かいタスクまでGitHubに流れていきます。公開する側や、チーム全員が見る側をすっきり保ちたいなら、片方向で十分です。one-wayでも「GitHub→Linear」は常に効きます。
ステップ3：プロジェクトを作る
ここからもLinearの画面（Web版）での操作です。左の「Projects」から新規作成し、名前を付けます（私は Promplet v1.1）。名前の下のサマリーに、1行だけ概要を書きました。
ここでのポイントは、Linearの「プロジェクト」は、GitHubでいうリポジトリ単位ではない、ということです。リポジトリと1対1で作るのではなく、「Promplet v1.1」のように、ひとまとまりの作業（バージョンやマイルストーンなど、管理したい作業の単位）でプロジェクトを作ります。1つのリポジトリの中に、v1.1・v1.2…と複数のプロジェクトをぶら下げていくイメージです。
ここで注意 説明（Description）の大きな空欄や、マイルストーンは、最初は空のままでOKです。
名前の下がサマリー（概要）、その下の大きな空欄がデスクリプション（説明）
ステップ4：Issueとサブイシューを作る
作ったプロジェクトを開いた状態で「New issue」からIssueを1件作ります。プロジェクトを開いて作れば、自動でそのプロジェクトに紐づきます。
次に、そのIssueを開いて、メニューから「Add sub-issue」を選び、サブイシュー（子Issue）を1件ぶら下げます。
ここで注意 サブイシュー作成のショートカットは
Ctrl + Shift + ↓（下矢印）です。Ctrl + Shift + Oは通常のIssue作成なので間違えやすいです。また「Add sub-issue」を選ぶと通常のIssue作成ダイアログが開きますが、それで正常です（親の下に紐づきます）。
ステップ5：カンバンボードでステータスを動かす
Issue一覧の表示をボードに切り替えます。右上の表示オプションでレイアウトを「Board」にするか、Ctrl + B でリスト表示とカンバンボード表示をトグル（交互に切り替え）できます。ステータスでグループ化したボードにして、カードをドラッグで Backlog → In Progress → Done と動かします。
ここで注意 ボードを使うのに、ビューを新規作成する必要はありません。表示を切り替えるだけです。中身が空のステータス列は自動で隠れるので、見当たらないときは「Show empty columns」で表示します。 もう一点。サブイシューを全部Doneにしても、親Issueは自動でDoneになりません。親子のステータスは独立しているので、親は自分で動かします。
ステップ6：既存のGitHub Issueをインポートする
ステップ2の同期だけだと、設定後に作られる新しいIssueは流れてきますが、既存のIssueは入ってきません。既存分は「Import issues」から一度だけ取り込みます。GitHubを選び、取り込み先のチームと対象リポジトリを指定して実行します。
途中で「ユーザーの対応付け（Map users）」が出たら、「Map to existing」でGitHub側の作者を自分のLinearアカウントに寄せます。
ここで注意 「同期」は今後の新規分、「インポート」は過去の既存分、という役割分担です。同期しただけで既存Issueが出てこないのは正常で、取り込みはこのインポートで行います。
ステップ7：エージェントをつなぐ前に「2つのルート」を知る
ここからCodexやClaude CodeをLinearにつなぎます。先に、つなぎ方が2ルートあることを知っておくと迷いません。
- クラウド（Web版）：CodexのWeb版（ブラウザ）などでLinearと連携し、Issueをクラウド上の作業環境で処理させるルート。Codexなら、Issueに @Codex を割り当て／メンションして呼びます。Claudeの場合は、Linear内蔵の「Coding sessions」にIssueを委譲する形が基本で、@Codex のような固定のメンション名で呼ぶわけではありません。いずれもプラン、GitHub連携、作業環境などの前提があります。
- ローカル（アプリ版）：手元のCodexアプリ（デスクトップアプリ）やClaudeアプリからLinearを参照・更新しながら、コード作業は手元のリポジトリで行うルート。Codexの場合は、Linearプラグインを追加すると、Linear用のスキルとLinear用のアプリ連携が入ります。クラウド用のCodex環境は不要です。
私は手元のCodexアプリやClaudeアプリで使いたかったので、ローカル（アプリ版）を選びました。
ここで紛らわしいのが、「Codex」にはWeb版とアプリ版（デスクトップ）があり、設定画面も別だという点です。CodexのWeb版でLinear連携を設定する方法と、Codexアプリ側でLinearプラグインを追加する方法は、目的が少し違います。LinearのIssueをクラウド上のCodexに委譲したいならWeb版／クラウド連携、手元のCodexアプリからLinearを読み書きしたいならアプリ側のプラグインを使います。
ここで注意 Linearのサイドバーにある「Connect Codex」やCodex Web版の「Linearにインストール」は、基本的にはクラウド版の入口です。手元で使うなら、Codexアプリ側の「プラグイン」からLinearを追加します。クラウド用の「環境」は、アプリ版でLinearを読み書きするだけなら要りません。 用語も整理しておくと、プラグイン＝追加機能のパッケージ、スキル＝作業手順のまとまり、アプリ連携／コネクタ＝外部サービスにつなぐ接続機能です（Codexでは「アプリ連携」、Claudeでは「コネクタ」と呼ぶ）。
ステップ8：Codexアプリをつなぐ【ローカル】
ここからは Codexアプリ（デスクトップアプリ）での操作です。Web版ではありません。
- Codexアプリのサイドバーにある「プラグイン」を開き、「Linear」を検索する
- Linearの「プラグインを追加」を押す（このとき、使い方をまとめた「スキル」も一緒に入ります）
- 追加の途中でLinearへのサインイン（OAuth）を求められるので許可する。［Linearに進む］と［高度な設定（ChatGPT.comを開く）］ボタンがあるので、私の場合は「高度な設定」を選択。ChatGPTのアプリ管理で「Linear」ページが表示されるので、［接続する］ボタンをクリック。次のダイアログ表示で［Linearでサインイン］をクリック。そこで認証画面が出て、承認しました
これでプラグインとスキルが追加され、Linear用のアプリ連携も有効になります。実際につながったかどうかは、ステップ10の読み取りテストで確認します。
ステップ9：Claudeアプリ（Claude Code）をつなぐ【ローカル】
考え方はCodexと近いですが、Claude側には「コネクタ」があり、ここが実際の接続を担います。
- 設定の中にある［プラグイン］（のAnthropic & パートナー）から「Linear」を追加する
- 「コネクタ」を開き、Linearを追加して［連携/連携させる］ボタンからサインイン（OAuth）する。アクセスを承認（Approve）すると完了です
ここで注意 プラグイン画面に「どこにつなぐ」設定が見当たらなくても正常です。サインインは「コネクタ」側、または初回利用時のOAuthで行われます。 ちなみに私の場合は、コネクタ上は「接続中」と表示されているのに、実際にはLinearのツールが使えませんでした。コネクタをいったん切断して再接続したら、使えるようになりました。
ステップ10：つながったか確認する（テスト）
UIの状態表示は場所によって食い違って見えることがあります。確実なのは、エージェントに実際にLinearを読み取らせることです。返ってきたデータが、接続先の動かぬ証拠になります。
私は次のように依頼して確認しました。
Linearに接続して、次を読み取って教えてください。 - アクセスできるワークスペース／チーム名と key - チーム名（key）のプロジェクト一覧 - 目的のプロジェクトに紐づくIssueを数件（ID・タイトル・ステータス） どのワークスペースに接続されているかも明記してください。
読み取りが通ったら、捨てIssueを1件作り、コメントを足し、ステータスをBacklog→In Progress→Doneと動かす書き込みテストもやると安心です。デスクトップアプリのボードを開いておくと、カードがリアルタイムで動くのが見えます。
まとめ：ここだけ注意（チェックリスト）
- この記事で扱うのは「同期」。コード連携（コミット/PRでステータスを動かす）は最後のヒントで簡単に触れる
- 「連携」（GitHubアカウントをつなぐ）と「同期」（Issueを流す）は別物。言葉を分けて捉える
- 「同期する」が指すのはコード連携かIssue同期か。同じIssueを両方に二重で作る必要はない
- 細かいタスクを全員が見る側に出したくないなら片方向（GitHub→Linear）
- Settingsはチーム名の横の∨（プルダウン）から開く
- サブイシュー作成は
Ctrl + Shift + ↓（Ctrl + Shift + Oは通常Issue） - カンバンは
Ctrl + Bでトグル。ビュー新規作成は不要。空の列は「Show empty columns」で出す - 親子のステータスは独立。子が全部完了でも親は手動で動かす
- 同期は今後分、既存分はインポート
- エージェント接続はクラウドとローカルの2ルート。手元で使うならプラグイン
- 接続確認はUI表示より「読み取りテスト」が確実
ヒント：コード連携（コミットやPRでステータスを動かす）とは
この記事では扱いませんでしたが、もう一つの連携「コード連携」も便利なので、考え方だけ簡単に紹介します。
仕組みはシンプルで、コミットメッセージにマジックワードとIssue番号を書いておくと、Linearのステータスが自動で動きます。
- 事前の準備（1回だけ）：コミット連動を有効化する
- ステップ1〜2で開いた「GitHubの連携設定」画面を下にスクロールする（チーム設定 → Integrations → GitHub の中です）
- 「Link commits to issues with magic words」をオンにする
- 使い方
- コミットメッセージに
Fixes ISK-7のように書く（リンクだけならPart of ISK-7） - そのコミットをデフォルトブランチ（main）に入れると、
Fixesを付けたIssueが自動で「完了（Done）」に動く - プルリクエスト（PR）を使う場合は、PRの下書き→マージに合わせてステータスが段階的に動く
- コミットメッセージに
そして、この作業はAIエージェントに任せるのが楽です。この記事で設定した接続が済んでいれば、「Issueを読んで実装し、Fixes ISK-7 のようなメッセージでコミットする」ところまで、CodexやClaude Codeにお願いできます。番号の付け方を手で覚えるより、まずAIに任せてみるのがおすすめです。
