【ITニュース解説】Connecting Zenn to a GitHub Repository: The Setup Steps and Two Pitfalls

日本の技術ブログプラットフォームZennと、ソースコード管理サービスGitHubを連携させる方法について解説する。この連携機能は、GitHubリポジトリにMarkdown形式で書かれた記事ファイルをプッシュするだけで、Zenn上に記事を自動で公開・更新できる非常に便利な仕組みだ。Web上のエディタを使わずに、普段使い慣れたエディタで執筆し、Gitのバージョン管理機能で記事の履歴をしっかりと残せる点が大きなメリットとなる。また、プライベートリポジリを利用すれば、執筆中の下書きやアイデアメモは非公開のまま保持し、公開したい記事だけをZennに反映させるといった柔軟な運用も可能だ。

このGitHub連携を正しく設定するための手順は以下の通りとなる。まず、Zennにログインし、ダッシュボードの中から「GitHub連携」の項目を開く。次に、Zennの画面に表示されている「リポジトリを接続」ボタンをクリックして、接続プロセスを開始する。すると、GitHubの認証画面へ遷移するので、そこでZennと連携させたいGitHubリポジリを選択する。セキュリティの観点から、すべてのリポジリにアクセスを許可するのではなく、特定の選んだリポジリのみにアクセス権限を与えることを強く推奨する。この手順で接続が完了すれば、その後、指定したリポジリの特定の場所にMarkdownファイルをプッシュするたびに、Zennへのデプロイ（公開・更新処理）が自動で実行されるようになる。デプロイの状況はZennダッシュボードのログで確認できる。ここで最も重要な点は、Zenn側から接続を開始するという流れを厳守することだ。

この連携設定には、初心者が陥りやすい二つの落とし穴があるため、具体的な注意点とその解決策も説明する。

一つ目の落とし穴は、「GitHub側からZennアプリをインストールしても連携が完了しない」という点だ。多くの人が最初にGitHub Marketplaceから「Zenn Connect」アプリをインストールしようとしがちだが、これだけではZennとGitHubアカウント間の正式な連携は確立されない。この場合、Zennのダッシュボードには連携状況が何も表示されず、エラーメッセージも出ないため、何が問題なのか分かりにくいという状況に陥る可能性がある。原因は、ZennのGitHub連携が、Zennの画面からOAuth認証とリポジリ選択を行うフローを前提としているためだ。GitHub側からのアプリインストールだけでは、Zennアカウントへの紐付けが行われない。もしすでにGitHub側からアプリをインストールしてしまった場合は、GitHubの設定画面の「Applications」からZenn Connectアプリを一度アンインストールする。その後、前述の「Zennの『リポジリを接続』ボタンから接続を開始する」という正しい手順を再度実行することで、問題なく連携が確立され、ダッシュボードに表示されるようになるだろう。

二つ目の落とし穴は、「接続前にプッシュされたコミットはデプロイされない」という点だ。GitHub連携を確立する前にすでにリポジリに記事ファイルなどをコミットしてプッシュしていた場合、Zennとの接続が完了しても、それらの過去のコミットが自動的にZennへデプロイされることはない。Zennの連携機能は、接続が確立された後に新しくプッシュされたコミットのみをデプロイの対象として検出するため、既存のコミットを遡って処理することはないのだ。この問題への解決策は非常にシンプルだ。ZennとGitHubの接続が完了した後に、リポジリに対して新しいコミットをプッシュするだけでよい。記事内容に変更がなくても、以下のように空のコミットを一つ作成してプッシュするだけで、最初のデプロイがトリガーされ、過去にプッシュしていた記事もZenn上に反映されるようになる。 git commit --allow-empty -m "trigger zenn deploy" git push このコマンドを実行することで、Zennは新しいプッシュを検知し、リポジリ内の記事を処理し始める。

Zennで記事として認識され、デプロイされるファイルには特定のルールがある。記事ファイルはGitHubリポジリ内のarticles/ディレクトリ配下に配置し、ファイル名は<slug>.mdという形式にする必要がある。<slug>の部分は、その記事のURLの一部となる識別子で、小文字の英数字とハイフンのみを使い、12文字から50文字の範囲で設定する必要がある。このスラッグの文字数制限を厳守しないと、デプロイ時にエラーが発生するため注意が必要だ。

また、記事ファイルの先頭には、「フロントマター」と呼ばれるYAML形式の設定情報を記述する。これは、記事のタイトルや種類、タグ、公開ステータスなどをZennに伝えるための重要なメタデータだ。具体的な記述例は以下のようになる。

---

title: "記事のタイトル" emoji: "💡" type: "tech" # 技術記事ならtech、アイデア記事ならidea topics: ["zenn", "github"] # 最大5つの小文字のタグ published: true # trueで公開、falseで下書き

published: falseと設定してプッシュすることで、記事はZenn上で下書きとして扱われ、公開されることはない。この機能を活用すれば、デプロイ設定が正しく機能しているか、または記事の内容を最終確認したい場合などに、安心してテストプッシュを行うことができる。プライベートリポジリと組み合わせれば、執筆から公開までのワークフローを安全かつ効率的に進めることが可能だ。

以上をまとめると、ZennとGitHubの連携をスムーズに行うためには、まず接続は必ずZennのダッシュボードにある「リポジリを接続」ボタンから開始すること、もしGitHub側からZennアプリをインストールしてしまった場合は、一度アンインストールしてからZenn側で再接続すること、そして接続が確立される前にプッシュされたコミットはデプロイされないため、連携後に新しくコミット（空コミットでも良い）をプッシュして最初のデプロイをトリガーすることが重要だ。記事ファイルのパスとスラッグの命名規則、そしてフロントマターによる設定も忘れずに行う必要がある。これらの手順と注意点を守ることで、Zennでの快適な技術記事執筆環境を構築できるだろう。