【Notion】NotionのGitHub連携でプレビューが出ない時の権限確認

NotionとGitHubを連携してコードやドキュメントのプレビューを表示しようとしたところ、「プレビューを読み込めません」といったエラーが出て作業が止まってしまうことがあります。この問題の多くは、GitHub側の権限設定が原因です。NotionはGitHubのAPIを通じてリポジトリの内容を取得するため、リポジトリへのアクセス権限や個人アクセストークンのスコープが適切でないとプレビューが表示されません。本記事では、権限に焦点を当てて問題の切り分け方と具体的な確認手順を解説します。

GitHub連携のプレビュー機能と必要な権限の基本

NotionのGitHub連携では、リポジトリ内のファイルをNotion上でプレビューできます。この機能は、NotionがGitHub APIを通じて指定されたリポジトリの内容を読み取ることで実現しています。そのため、Notionがリポジトリにアクセスするための適切な権限が設定されている必要があります。

必要な権限は大きく分けて以下の3つです。

• リポジトリへのアクセス権限: 連携するリポジトリに対して、自分(またはNotionで使用するGitHubアカウント)が読み取り権限を持っていること。プライベートリポジトリの場合は特に注意が必要です。
• 個人アクセストークンのスコープ: 連携時に使用するトークンに repo スコープ(プライベートリポジトリの場合)または public_repo スコープが含まれていること。
• 組織のポリシー: 所属組織がOAuth Appや個人アクセストークンの使用を制限している場合、連携がブロックされることがあります。

これらの権限が一つでも欠けていると、プレビューが表示されなくなります。

プレビューが出ない原因を切り分けるための確認手順

問題が発生したら、まずはどの段階でエラーが出ているかを確認します。以下の手順で原因を切り分けてください。

1. Notion上のエラーメッセージを確認する: プレビューが表示されない場合、Notionのブロックに「権限がありません」や「404 Not Found」といったメッセージが表示されることがあります。エラーの内容をメモしておきます。
2. GitHub上でリポジトリにアクセスできるか確認する: ブラウザで該当のリポジトリを開き、ファイルの内容が表示されるか確認します。アクセスできない場合は、アカウントの権限が不足しています。
3. 連携に使用しているGitHubアカウントを確認する: Notionの設定画面で現在連携しているGitHubアカウントを確認します。意図しないアカウントで連携していると権限不足になることがあります。
4. 個人アクセストークンを発行したか確認する: Notionとの連携方式によっては、個人アクセストークン(PAT)が必要です。PATを生成した際のスコープ設定を確認します。有効期限が切れている場合もあります。
5. 組織の設定を確認する: 所属組織が「OAuth App access restrictions」や「Personal access token policy」を有効にしている場合、事前に承認を得る必要があります。管理者に問い合わせましょう。

これらの確認で、おおよその原因が特定できます。

権限設定の確認手順

ここでは、具体的に権限を確認・修正する手順を説明します。

リポジトリの権限確認

連携したいリポジトリに対して、自分のアカウントが読み取り権限(Pull)を持っているか確認します。プライベートリポジトリの場合は、コラボレーターとして追加されている必要があります。

1. GitHubで対象リポジトリのページを開きます。
2. 「Settings」→「Collaborators and teams」を開きます。
3. 自分がリストに含まれているか、または所属するTeamに読み取り権限が与えられているか確認します。
4. 権限がない場合は、リポジトリ管理者に読み取り権限を依頼してください。

組織の権限確認

組織がThird-party application access policyを設定している場合、個人アクセストークンの使用が制限されます。以下の手順で確認します。

1. GitHubのSettings画面を開きます。
2. 「Applications」→「Personal access tokens」を開きます。
3. 対象のトークンをクリックして、「Organization access」の項目を確認します。
4. 該当の組織が「Read」または「Write」として許可されていない場合、組織の管理者に承認を依頼するか、トークンを再生成して組織を承認する必要があります。

個人アクセストークンのスコープ確認と再発行

トークンのスコープが不足していると、リポジトリの内容を読み取れません。以下の手順で確認・修正します。

1. GitHubの「Settings」→「Developer settings」→「Personal access tokens」→「Tokens (classic)」を開きます。
2. 連携に使用しているトークンを見つけ、「Edit」をクリックします。
3. リポジトリへのアクセスに必要なスコープがチェックされているか確認します。プライベートリポジトリの場合は repo スコープ、パブリックのみの場合は public_repo で十分です。
4. スコープが不足している場合は、適切なスコープを追加して「Update token」をクリックします。
5. トークンの有効期限が切れていないかも確認します。切れている場合は新しいトークンを生成し、Notionの連携設定を更新します。

よくある失敗パターンと対処法

実際に発生しやすいミスとその対処法をまとめました。

失敗パターン	原因	対処法
「404 Not Found」エラー	リポジトリが存在しないか、アクセス権限がない。	リポジトリのURLが正しいか確認、コラボレーター権限を依頼。
「403 Forbidden」エラー	トークンのスコープ不足、または組織の制限。	トークンスコープの修正、組織の承認を得る。
「401 Unauthorized」エラー	トークンが無効または期限切れ。	トークンを再発行してNotionの連携を更新。
プレビューが空欄で何も表示されない	ファイル形式がサポートされていない、またはネットワークの問題。	サポートされているファイル形式(コード、マークダウンなど)を確認、会社のネットワークプロキシ設定を確認。
連携設定が保存できない	Notion側の不具合、またはGitHub側のレート制限。	時間をおいて再試行、ブラウザのキャッシュをクリア。

権限以外の原因も考慮する

ただし、すべてが権限問題とは限りません。たとえば、会社のネットワークがGitHub APIへのアクセスを制限している場合や、Notion側のサーバー障害が原因の場合もあります。そのため、権限を確認しても解決しない場合は、以下の点も確認してください。

• ブラウザの開発者ツールでNetworkタブを開き、エラーレスポンスのステータスコードを確認する。
• 別のネットワーク(自宅やテザリングなど)で試して同じ現象が起きるか確認する。
• Notionのサービスステータスページ(status.notion.so)で障害情報を確認する。

管理者に依頼する前に確認すべき情報

会社のGitHub組織で連携がうまくいかない場合、管理者に問い合わせる前に以下の情報を整理しておくとスムーズです。

• エラーメッセージのスクリーンショット:Notionに表示されているエラー内容を撮影しておきます。
• 使用しているGitHubアカウントのユーザー名:連携に使っているアカウントが組織のメンバーかどうか確認できるようにします。
• リポジトリのURL:問題が発生するリポジトリの完全なURLを伝えます。
• 個人アクセストークンの有無とスコープ:トークンを使っている場合は、そのスコープと有効期限を確認します。ただし、トークン自体は共有しないでください。
• 組織のポリシー関連:OAuth App制限やPAT制限が有効になっているかどうかを管理者に確認してもらうための依頼事項としてまとめます。

管理者への依頼文の例を以下に示します。

「NotionのGitHub連携でプレビューが表示されません。エラーは403が返ってきています。私のアカウント(ユーザー名:xxx)はリポジトリ(URL:yyy)に対して読み取り権限を持っているはずですが、組織のPAT制限が原因かもしれません。お手数ですが、組織の設定とトークンの承認状況を確認していただけますでしょうか。」

よくある質問(FAQ)

Q: NotionでGitHubプレビューを使うには、有料プランが必要ですか?

A: いいえ、NotionのGitHub連携はすべてのプランで利用できます。ただし、プレビュー機能は無料プランでも使用可能です。ただし、Notionのワークスペース内でGitHubブロックを追加するには、ワークスペースが有料プランである必要はありません。

Q: パブリックリポジトリのプレビューも表示されません。何が問題ですか?

A: パブリックリポジトリの場合でも、以下の原因が考えられます。トークンに public_repo スコープが含まれていない、トークンの有効期限が切れている、または組織の制限で外部への連携がブロックされている可能性があります。まずはトークンのスコープと有効期限を確認してください。

Q: 連携を解除して再設定すれば直りますか?

A: 権限問題が原因の場合、再設定だけでは解決しないことが多いです。まずは権限設定を修正してから、Notionの連携設定を更新(トークンを再入力)する必要があります。再設定前に必ずGitHub側の権限を確認してください。

Q: プレビューが表示されるまでに時間がかかります。なぜですか?

A: NotionはGitHub APIを呼び出してデータを取得するため、リポジトリのサイズやファイル数によって読み込みに時間がかかることがあります。また、GitHub APIのレート制限(1時間あたりのリクエスト数)に達している場合も遅延が発生します。しばらく待つか、APIレート制限の状況を確認してみてください。

まとめ

NotionのGitHub連携でプレビューが表示されない場合、多くの原因は権限設定にあります。リポジトリの読み取り権限、個人アクセストークンのスコープ、組織のポリシーの3点を確認することで、大部分の問題は解決できます。エラーメッセージを手がかりに、適切な権限を付与してもらいましょう。もし権限に問題がない場合は、ネットワークやNotion側の障害を疑ってみてください。事前に管理者へ確認すべき情報を整理しておくことで、問い合わせもスムーズになります。

🧩

Notionトラブル完全解決データベース 共有、権限、データベース、Notion AI、インポートで止まる問題を横断的に確認できます。