目次
GitHub Actions のワークフローを使えば、main へのプッシュ時に同じ Markdown 記事を Zenn と Qiita に公開できます。重要なのは、Qiita の記事 ID を Git に保存することです。保存しないと、次回以降の実行で記事が重複する可能性があります。
要点#
- Zenn の記事は
articles/に、生成した Qiita 用ファイルはpublic/に置き、ファイル名を揃える。 - 編集時に既存の記事を更新できるよう、Qiita の記事 ID を保持する。
- Zenn の
published: falseは公開処理を止める設定として扱う。既存の Qiita 記事は非公開にならない。 - 公開後に CLI が更新したファイルをコミットし、削除は明示的に処理する。
Git を原本にする#
リポジトリを Zenn に連携し、必須の articles/ ディレクトリをリポジトリのルートに置きます。たとえば、ソースファイル articles/github-actions-sync.md から、Qiita 用の public/github-actions-sync.md を生成します。
同じファイル名で両プラットフォームの記事を対応付けます。別途マッピングファイルは不要ですが、ソースファイルの名前を変更する際は注意が必要です。変換処理が以前の Qiita 用ファイルを見つけられないと、ID を引き継げず、別の記事を作成する可能性があります。
編集するのは articles/ 内のソースです。public/ は記事を書く第2の場所ではなく、生成コンテンツと永続的な公開状態を保存する場所として扱います。Qiita 上で直接加えた変更は、次回の同期で上書きされる可能性があります。
ワークフローを設定する#
記事の書き込み権限を持つ Qiita アクセストークンを作成し、リポジトリシークレット QIITA_TOKEN として保存します。公開状態をコミットできるよう、ワークフローに contents: write 権限を付与します。リポジトリのルールでも、そのプッシュを許可する必要があります。
GitHub Actions を次のように設定します。
articles/**を変更するmainへのプッシュと、手動実行用のworkflow_dispatchをトリガーにする。- 公開ジョブが重複実行されないよう、単一の同時実行グループで
cancel-in-progress: falseを設定する。 - リポジトリをチェックアウトし、サポート対象の Node.js をインストールする。
- バージョンを固定した
@qiita/qiita-cliとjs-yamlをインストールする。コミット済みのロックファイルとnpm ciの使用が望ましい。
ジョブはチェックアウト、変換、公開、コミットの順に実行します。Node.js とアクションのバージョンを選ぶ前に、CLI の最新の要件を確認してください。古い例のバージョンを、そのまま固定の標準にしないようにします。Qiita トークンは公開ステップの環境変数に設定します。
フロントマターを変換する#
行単位の置換ではなく、ライブラリで YAML を解析します。Markdown 本文をコピーし、次の対応表に従って Qiita 用フロントマターを生成します。
| Qiita のフィールド | 値 | |---|---| | title | Zenn の title | | tags | 最大5個のトピック文字列 | | private | false | | id | 既存の Qiita ID、または null | | updated_at | 既存の値、または空文字列 | | organization_url_name | 既存の値、または null | | slide | false |
これらは CLI の Markdown 形式に対応する値であり、API のリクエスト形式とは異なります。提示された実装では、タグを文字列にし、新規記事の ID と組織を null にすることで、Bad request エラーが解消しました。固定する CLI バージョンで、この形式を検証してください。
対象となる各ソースファイルについて、既存の public/<slug>.md を上書き前に読み込みます。その ID と更新日時を引き継ぎます。未完成の記事を誤って公開可能と判断しないよう、公開メタデータが欠落している場合や不正な場合はエラーにします。
公開後に ID を保存する#
Qiita CLI は公開後、ローカルの Markdown ファイルに記事 ID を書き戻します。GitHub Actions のランナーは一時的な環境なので、次回の実行までにその変更をリポジトリへ反映する必要があります。
公開に成功したら、public/ 内の変更されたファイルをコミットし、main にプッシュします。提示された実装では、CLI の public/.remote/ キャッシュも保持します。公開に成功してもコミットに失敗した場合は、再実行する前に公開済みの記事 ID を回収してください。そうしないと、記事が重複する可能性があります。
ジョブを直列化するだけでなく、変換前にブランチの最新状態を取得してください。直列化だけでは、待機中の実行がボットの最新コミットをチェックアウトするとは限りません。最後のプッシュが並行した変更と競合した場合は、ID を失わないように解決します。新しい編集を始める前に、ローカルでプルしてください。トリガーを articles/** に限定すると、生成ファイルだけのコミットでこのワークフローが再実行されるのを防げます。
下書きと削除を扱う#
Zenn と Qiita では公開制御が異なります。published: false にすると Zenn の記事を下書きに戻せますが、すでに公開されている Qiita の記事は非公開になりません。パイプラインでは、その Qiita 記事を変更せずに残します。
実装には見落としやすい落とし穴があります。変換をスキップしても、既存の public/ ファイルは qiita publish --all の対象から外れません。公開対象の記事を明示的にリスト化し、固定した CLI バージョンがサポートする選択方法で、それらだけを公開してください。スキップした記事の保存済み ID は保持します。
削除には別の手順が必要です。
- まずソース記事を Qiita の公開対象から外す。外さないと、変換処理で再作成される可能性がある。
- Qiita 上の記事を削除する。
- 生成ファイルと対応するリモートキャッシュを削除し、コミットする。
- 公開前に、共通で使う Markdown、画像 URL、タグを確認する。Zenn 固有のブロックやリポジトリ相対パスの画像は、変換または置き換えが必要。
次のステップ#
ワークフローでテスト記事を1件公開し、編集して再実行してください。Qiita で同じ記事 ID が更新されることを確認してから、リポジトリ内の残りの記事の同期を有効にします。
出典: https://zenn.dev/ot4ma_zenn/articles/20261025-sun-zenn_qiita_pipeline
目次
