Notion GitHub連携の使い方｜開発タスクとドキュメントをつなぐ

NotionとGitHubを一緒に使う開発チームは多いです。

仕様書はNotionにある。

実装タスクはGitHub Issuesにある。

コード変更はPull Requestにある。

開発方針や議事録はNotionに残っている。

リリース前の確認は、Notionのチェックリストで見たい。

こうした運用では「Notion GitHub連携」が気になります。

ただし、NotionとGitHubの連携を考えるときは、最初に誤解を潰す必要があります。

• GitHub AIコネクターを入れれば、IssueやPRがNotion DBに同期されると思っている
• NotionのタスクDBをGitHub Issuesの代わりにしようとしている
• 仕様書、Issue、PR、議事録のどれが正か決まっていない
• GitHubのステータスとNotionのステータスが別々に更新される
• AI検索で見つけたPR内容を、確認済みの仕様として扱ってしまう
• プライベートリポジトリの権限をNotion側だけで判断している
• リリース判断に必要なレビュー、テスト、承認がDB上で分からない

こうなると、連携しているように見えても、開発管理は崩れます。

Notion GitHub連携は、GitHubをNotionに置き換えることではなく、コードと実装状態はGitHub、仕様と意思決定はNotion、管理ビューはNotion DBに分ける設計 として考えるべきです。

この記事では、NotionとGitHubの連携を、GitHub AIコネクター、Notion API、開発タスクDB、仕様書、PR・Issue、権限、レビュー運用まで実務目線で整理します。

先に結論：コードはGitHub、仕様と判断はNotion

NotionとGitHubを連携するときは、まず役割を分けます。

情報	正とする場所	理由
コード、ブランチ、コミット	GitHub	実装の原本
Pull Request	GitHub	差分、レビュー、CI、マージ状態を持つ
Issue、バグ、開発チケット	GitHub Issues、または開発管理ツール	実装と紐づく状態管理に強い
仕様書、要件、背景	Notion	文脈、説明、意思決定を残しやすい
会議メモ、決定事項	Notion	議論と決定を後から追える
社内レビュー、リリース確認	Notion DB	担当者、期限、確認状態を見やすい
コードやPRの検索	GitHub AIコネクター	Notion AIからGitHub情報を探せる

GitHubは、実装の正です。

どのコードが変わったか。どのPRがレビュー中か。CIが通っているか。どのIssueが閉じたか。これはGitHub側で見るべきです。

Notionは、開発の文脈を管理する場所です。

なぜその機能を作るのか。どの顧客要望が背景にあるのか。どの仕様で合意したのか。リリース前に誰が何を確認するのか。こうした情報はNotion DBやNotionページで整理します。

Notionプロジェクト管理の作り方

連携でできること

NotionとGitHubまわりの連携は、1つではありません。

実務では、次の4つに分けます。

連携の種類	目的	主な使いどころ
GitHub AIコネクター	GitHub上のコード、PR、IssueをNotion AIから検索する	仕様確認、実装調査、過去PRの確認
Notion API	Notion DBやページを外部処理から読み書きする	仕様DB、リリースDB、確認DBの更新
Notion DB運用	仕様、レビュー、リリース確認を管理する	担当者、期限、確認状態
GitHubリンク運用	Issue、PR、READMEへ戻れるようにする	Notionページと実装の接続

Notion公式ヘルプでは、GitHub AIコネクターはGitHubのコード、PR、Issue、ファイル、READMEを検索対象にできると説明されています。

Notion公式ヘルプ：GitHub AI Connector

Notion公式APIドキュメントでは、Notion接続が外部ツールとワークスペースをつなぎ、REST APIでページ、データベース、ユーザー、コメントなどを読み書きできることが説明されています。

Notion公式API：Overview

Notion公式のデータベースオートメーションでは、ページ追加、プロパティ編集、定期実行などをトリガーに、プロパティ編集、ページ追加、通知、Webhook、Slack通知などを設定できます。

Notion公式ヘルプ：データベースオートメーション

ただし、これらは同じものではありません。

できること	できたと誤解しやすいこと
GitHubをNotion AIから検索する	GitHub IssuesがNotion DBへ同期される
Notion APIでDBを更新する	GitHubの実装状態が自動で正確に反映される
Notion DBでレビュー状態を見る	PRレビューやCI状態までNotionが正になる
GitHubリンクをNotionに貼る	仕様と実装の整合が自動で保証される

連携方法より先に、どの情報をどこで管理するかを決めます。

GitHub AIコネクター

GitHub AIコネクターは、GitHubの情報をNotion AIから探すための連携です。

公式ヘルプでは、利用にはGitHub organization ownerとNotion workspace ownerが必要で、ワークスペースはBusinessまたはEnterpriseプランかつ複数メンバーである必要があると説明されています。

また、設定後は、パブリックリポジトリは追加認証なしで扱え、プライベートリポジトリは各メンバーがGitHub認証してアクセス権を確認する必要があります。

実務での使いどころは次の通りです。

使いどころ	例
最近の変更を調べる	先週の認証まわりのPRを確認する
実装例を探す	既存のエラーハンドリング実装を探す
Issueの状態を確認する	関連Issueがまだ開いているか見る
仕様書と実装の差分を調べる	Notionの仕様とPRの差分を比較する
セキュリティ方針を確認する	APIエンドポイントの認可パターンを探す

公式ヘルプでは、初期設定後、PRとIssueはセットアップ完了時点から過去1年分をインデックスでき、コードファイルやMarkdown、READMEは期間制限なくアクセスできると説明されています。

また、接続完了には最大72時間、新しいGitHubデータの反映には初期設定後も最大3時間かかる場合があるとされています。

このため、GitHub AIコネクターをリアルタイムのリリース判定に使うのは危険です。

AI検索に向く	AI検索だけでは足りない
過去PRの調査	マージ可否の最終判断
実装箇所の探索	CI結果の確認
Issueの背景把握	本番反映の確認
READMEやコードの検索	セキュリティレビューの承認

AI検索は、調査の入口です。

正式な実装状態はGitHubで確認します。

Notion APIでつなぐ場合

Notion APIを使うと、Notion DBやページを外部処理から読み書きできます。

GitHub連携で使うなら、たとえば次のような構成です。

使い方	内容
IssueリンクをNotion仕様DBへ保存	仕様と実装チケットを紐づける
PRリンクをリリース確認DBへ保存	リリース対象のPRを一覧化する
GitHub ActionsからNotion DBを更新	デプロイ候補、確認待ちなどを更新する
Notion DBからGitHub Issue作成	仕様レビュー後に開発チケットを起票する
リリースノート下書きをNotionに作成	マージ済みPRを人が確認する

ただし、API連携は安易に双方向同期にしない方がよいです。

双方向同期で起きる問題	対策
GitHubとNotionのステータスが競合する	正とする場所を決める
手動変更と自動更新が衝突する	自動更新するプロパティを限定する
権限のないリポジトリ情報がNotionに広がる	対象DBと公開範囲を限定する
CI失敗やAPI失敗でNotionが古くなる	更新日時と同期状態を持つ
Issue削除やPRリネームに追随できない	GitHub URLと外部IDを残す

Notion API公式ドキュメントでは、接続ごとに呼び出せるAPI、読み書きできる内容、認証方法、権限を定義し、接続はページやDBへの明示的なアクセス許可が必要だと説明されています。

つまり、Notion API連携では、最初に対象DBと権限を絞ります。

すべてのワークスペースを読ませるのではなく、開発管理用DB、リリース確認DB、仕様DBなど、連携に必要な場所だけに限定します。

開発タスクDBの設計

Notion側に開発タスクDBを作る場合、GitHub Issuesと役割が重なりすぎないようにします。

Notionの開発タスクDBは、実装チケットそのものではなく、仕様、確認、社内調整に寄せる方が安定します。

プロパティ	型	目的
タスク名	タイトル	作業や確認内容を短く表す
種別	セレクト	仕様、実装、レビュー、リリース、調査
関連仕様	リレーション	仕様書DBへ紐づける
GitHub Issue URL	URL	実装チケットへ戻る
Pull Request URL	URL	PRへ戻る
担当者	ユーザー	Notion側の確認責任者
開発担当	テキスト、ユーザー	実装担当者
確認者	ユーザー	仕様や受け入れ確認をする人
期限	日付	社内確認の期限
ステータス	ステータス	未整理、仕様確認中、実装中、レビュー待ち、リリース確認、完了
GitHub状態	セレクト	open、review、merged、closed、unknown
同期状態	セレクト	手動、同期済み、同期エラー、要確認

ステータス名は、GitHubの状態と同じにしすぎない方がよいです。

GitHubの状態は、PRやIssueの状態です。

Notionの状態は、業務として何を確認するかです。

GitHub側	Notion側
Issue open	仕様確認中、実装中
PR open	レビュー待ち
PR merged	リリース確認
Issue closed	完了、または確認済み
CI failed	要確認、差し戻し

Notion側で見るべきなのは、社内の判断が必要なものです。

実装の詳細状態はGitHubで見ます。

Notionタスク管理の作り方

仕様書とPRの紐づけ

Notion GitHub連携で価値が出やすいのは、仕様書とPRをつなぐことです。

仕様書だけNotionにあり、PRだけGitHubにあると、なぜその実装になったのかが後から追いにくくなります。

仕様書DBには、次のプロパティを用意します。

プロパティ	型	目的
仕様名	タイトル	機能や変更内容を識別する
背景	テキスト	顧客要望、社内課題、障害背景
関連プロジェクト	リレーション	プロジェクトDBとつなぐ
関連Issue	URL、リレーション	GitHub Issueへ戻る
関連PR	URL、リレーション	Pull Requestへ戻る
決定事項	リレーション	議事録や決定事項DBへつなぐ
受け入れ条件	テキスト	完了判定を明確にする
確認者	ユーザー	誰が仕様を承認するか
ステータス	ステータス	下書き、確認待ち、確定、変更中、廃止

PR本文には、Notion仕様書へのリンクを貼ります。

Notion仕様書には、PRとIssueへのリンクを貼ります。

これだけでも、かなり運用は安定します。

場所	残す情報
Notion仕様書	背景、目的、受け入れ条件、判断理由
GitHub Issue	実装チケット、議論、担当、ラベル
Pull Request	コード差分、レビュー、CI、マージ履歴
Notion議事録	決定事項、未解決論点、確認者

GitHub AIコネクターは、後からPRやコードの文脈を探すときに使います。

ただし、正式な仕様変更はNotion仕様書に反映します。

AIが見つけたPR説明を、そのまま仕様として扱わない方がよいです。

権限とリポジトリ範囲

GitHub連携では、権限が重要です。

Notion公式ヘルプでは、GitHub AIコネクターは各ユーザーがGitHubでアクセス権を持つコンテンツだけを検索できるように権限をマッピングすると説明されています。

また、プライベートリポジトリを扱う場合は、各メンバーがGitHubへログインして認証する必要があります。

それでも、Notion側に情報を転記するときは注意が必要です。

情報	注意点
プライベートリポジトリのコード	Notionページへ貼りすぎない
セキュリティ修正PR	共有範囲を限定する
顧客固有の障害内容	顧客情報と技術情報を分ける
認証、決済、個人情報まわりの実装	必要な人だけが見られる場所に置く
外部委託先が見る仕様書	内部PRや脆弱性情報を出しすぎない

GitHub側で見られる人と、Notion側で見られる人は一致しないことがあります。

AIコネクターの検索権限が守られていても、Notionページに手動で貼った情報はNotion側の共有範囲に従います。

そのため、Notionに残す情報は要約とリンク中心にします。

コードの詳細、秘密情報、脆弱性の具体的な悪用条件は、GitHubやセキュリティ管理の場所に残します。

使い分けの判断

NotionとGitHubの連携は、目的によって設計が変わります。

やりたいこと	現実的な設計
GitHubの過去PRやコードをNotionから探したい	GitHub AIコネクター
仕様書とPRを紐づけたい	Notion仕様DBにIssue/PR URLを持つ
リリース確認を一覧化したい	Notionリリース確認DBを作る
Issueの実装状態を厳密に管理したい	GitHub Issuesを正にする
NotionからIssueを起票したい	APIまたは外部自動化で片方向に作成する
PRマージ後に社内確認を回したい	GitHub ActionsやWebhookでNotion確認DBを更新する
開発スプリントを厳密に回したい	GitHub Projects、Jira、Linearなどを検討する

小さく始めるなら、最初は自動同期を作らなくてよいです。

次の3つだけでも効果があります。

最初にやること	理由
Notion仕様書にIssue/PRリンクを置く	仕様と実装を行き来できる
PR本文にNotion仕様書リンクを置く	レビュー時に背景へ戻れる
Notion確認DBでリリース前チェックを管理する	技術レビュー以外の確認漏れを防ぐ

そのうえで、二重入力が増えた部分だけAPIやWebhookで自動化します。

最初から全Issue、全PR、全仕様を双方向同期しようとすると、保守コストが上がります。

Notion GitHub連携の基本は、コードの正をGitHubに残し、仕様と判断の正をNotionに残すことです。

この分担を守れば、Notionは開発の文脈を整理する場所として機能します。

逆に、この分担を曖昧にすると、NotionもGitHubも古い情報を抱えるだけになります。