Zenn CLI導入とGitHub連携のハマりポイント・運用覚書
Zenn CLIを用いてローカルで記事を執筆し、GitHub経由で自動投稿・公開する際に遭遇したトラブルと解決策のまとめ。
1. Zenn CLIの初期セットアップ
Zennコンテンツ管理用のディレクトリで以下を実行して環境を構築する。
npm init --yes
npm install zenn-cli
npx zenn initarticles/: 記事用マークダウンファイルを配置。books/: 本用マークダウンファイルを配置。npx zenn preview: ローカルサーバーが起動しhttp://localhost:8000でプレビュー可能。
2. 記事フロントマター（ヘッダー）のハマりポイント
① タイトルの文字数制限
- 制限: タイトルは 70文字以内 で指定する必要がある。
- エラー事例: 70文字を超えると
npx zenn previewや検証時に警告が表示されるため、簡潔かつ分かりやすいタイトルに要約する。
② トピック（topics）の個数制限
- 制限:
topicsに指定できるタグは 最大5個まで（配列形式）。 - エラー事例: 6個以上指定するとフォーマット違反となるため、検索性・注目度の高い代表的な5つを厳選する。
topics: ["linux", "hermesagent", "neovim", "tmux", "linuxmint"]
3. GitHub連携と git push 時の認証エラー
① HTTPSでの認証エラーと Personal Access Token (PAT)
- 現象:
git push時に GitHub のログインパスワードを入力しても拒否される。 - 原因: 2021年以降、GitHubでは通常のパスワードによる Git 認証が廃止されたため。
- 対策:
- GitHubの Settings -> Developer settings -> Personal Access Tokens (classic) を開く。
repo権限を付与したトークン（ghp_...）を発行する。Password:にログインパスワードではなく、発行した トークン文字列 を入力する。
② 次回以降のトークン入力省略設定
毎回トークンを入力するのを防ぐため、以下のコマンドを実行してPCに認証情報を保存させる。
git config --global credential.helper store③ Permission denied (publickey) エラー
- 現象: リモートURLを SSH (
git@github.com:...) に設定した際アクセスが拒否される。 - 原因: PCのSSH鍵がGitHubアカウントに未登録のため。
- 対策: SSH鍵をGitHubに登録するか、
git remote set-url origin https://github.com/ユーザー名/リポジトリ名.gitで HTTPS に戻して PAT 認証を行う。
4. 公開フラグ（published）とブランチ運用
① 公開コントロール
published: false: 下書き状態。mainブランチに push しても Zenn 上では非公開・無視される。published: true: 公開状態。Zennと連携したリポジトリに push されると自動的に Zenn に公開される。
② おすすめの運用ワークフロー
- 普段の執筆:
published: falseのままmainブランチで作業し、定期的にgit pushしてバックアップを取る（Zennには公開されない）。 - 投稿時: 記事が完成したら
published: trueに変更してgit pushする。
関連記事
- Zenn公式: Zenn CLI ドキュメント
- GitHub公式: GitHub CLI 認証
Git-認証-PAT-SSH/Zenn記事執筆ワークフロー/GitHub-Actions-自動デプロイ— 個別技術メモ（未作成・予定）