はじめに
Qiitaで技術記事を執筆する際、記事をGitHubで管理し、ローカル環境から自動投稿できる仕組みを構築しました。
今回実現したかったのは、以下の3点です。
- 記事をMarkdown形式で管理し、GitHubで変更履歴を残す
- VS Codeなどのエディタで記事を執筆する
- GitHubにPushするだけでQiitaへ自動投稿・更新する
これらは、Qiita公式のQiita CLIとGitHub Actionsを組み合わせることで実現できます。
本記事では、実際に構築した手順に加えて、途中で遭遇したエラーや、既存記事をGitHubで管理する際の注意点についても解説します。
1. 全体構成
今回構築する仕組みは以下のとおりです。
【ローカルPC】
VS CodeでMarkdown記事を作成・編集
│
│ git push
▼
【GitHub】
記事のソースコードを管理
│
│ mainブランチへのPush
▼
【GitHub Actions】
Qiita CLIを自動実行
│
│ Qiita API
▼
【Qiita】
記事を新規投稿・更新
│
│ 記事IDや更新日時を反映
▼
【GitHub】
Actionsが変更を自動コミット
│
│ git pull
▼
【ローカルPC】
記事IDなどを同期
使用する技術は以下のとおりです。
| 技術 | 用途 |
|---|---|
| Git | ローカルでの記事のバージョン管理 |
| GitHub | 記事の保管・変更履歴管理 |
| Qiita CLI | 記事の作成・プレビュー・投稿 |
| GitHub Actions | 投稿処理の自動化 |
| Qiita API | Qiitaへの記事の投稿・更新 |
GitHub Actionsを使用するため、投稿用にサーバーを用意する必要はありません。
2. Qiita CLIのインストール
2.1 Node.jsの確認
Qiita CLIを利用するには、Node.jsが必要です。
Qiita CLIの公式ドキュメントでは、Node.js 22.22.1以上が要求されています。
まずはインストール状況を確認します。
node -v
npm -v
Node.jsがインストールされていない場合は、Node.js公式サイトなどから導入してください。
2.2 作業ディレクトリの作成
記事を管理するディレクトリを作成します。
mkdir qiita-articles
cd qiita-articles
Node.jsのプロジェクトを初期化します。
npm init -y
続いて、Qiita CLIをインストールします。
npm install @qiita/qiita-cli --save-dev
インストール後、バージョンを確認します。
npx qiita version
2.3 Qiita CLIの初期化
以下のコマンドを実行します。
npx qiita init
初期化すると、主に次のファイルが生成されます。
qiita-articles/
├── .github/
│ └── workflows/
│ └── publish.yml
├── node_modules/
├── .gitignore
├── package.json
├── package-lock.json
└── qiita.config.json
それぞれの役割は以下のとおりです。
| ファイル | 役割 |
|---|---|
publish.yml |
GitHub Actionsのワークフロー |
.gitignore |
Gitの管理対象外ファイルの指定 |
package.json |
Node.jsプロジェクトの設定 |
package-lock.json |
依存パッケージのバージョン情報 |
qiita.config.json |
Qiita CLIの設定 |
特に重要なのが、.github/workflows/publish.ymlです。
このファイルによって、GitHubへのPushをきっかけにQiitaへの自動投稿が実行されます。
3. Qiitaのアクセストークンを取得
GitHub ActionsからQiitaへ記事を投稿するには、Qiita APIの認証が必要です。
まず、以下のページでアクセストークンを発行します。
権限には以下の2つを指定します。
-
read_qiita:記事などの読み取り -
write_qiita:記事の投稿・更新
発行したトークンは安全な場所に保管してください。
アクセストークンをGitHubのリポジトリに直接記載してはいけません。
3.1 ローカル環境でログイン
Qiita CLIにログインします。
npx qiita login
トークンの入力を求められるので、発行したアクセストークンを入力します。
正常に認証されれば、ローカル環境からQiita CLIを使用できるようになります。
なお、このログイン操作はローカルPC用の認証です。
GitHub Actions側には、別途GitHub Secretsを登録する必要があります。
4. GitHubリポジトリの作成
GitHubで記事管理用のリポジトリを作成します。
今回は以下の名前とします。
qiita-articles
GitHubの新規リポジトリ作成画面から作成します。
リポジトリ作成後、ローカルで以下を実行します。
git init
git branch -M main
git add .
git commit -m "Initial Qiita setup"
続いて、GitHubのリモートリポジトリを登録します。
git remote add origin https://github.com/USERNAME/qiita-articles.git
USERNAMEは自分のGitHubユーザー名に置き換えてください。
最後にPushします。
git push -u origin main
これでGitHubへのアップロードが完了します。
補足:origin already existsが発生した場合
すでにoriginが登録されている場合、次のエラーが発生します。
error: remote origin already exists.
その場合は、git remote addではなく、以下のコマンドで既存のURLを変更します。
git remote set-url origin https://github.com/USERNAME/qiita-articles.git
登録されたURLは以下で確認できます。
git remote -v
5. GitHub Secretsにトークンを登録
ここが認証設定で最も重要な部分です。
GitHubリポジトリの以下の画面にアクセスします。
Settings → Secrets and variables → Actions
New repository secretを選択し、以下の情報を登録します。
| 項目 | 設定内容 |
|---|---|
| Name | QIITA_TOKEN |
| Secret | Qiitaで発行したアクセストークン |
QIITA_TOKENという名前は正確に指定してください。
GitHub Actionsは、以下の記述でSecretを参照します。
qiita-token: ${{ secrets.QIITA_TOKEN }}
Secretに登録することで、アクセストークンをリポジトリ内のコードに直接書かずに認証できます。
6. GitHub Actionsの設定
npx qiita initを実行すると、投稿用のワークフローが自動生成されます。
ファイルの配置場所は以下のとおりです。
.github/workflows/publish.yml
今回使用する設定例です。
name: Publish articles
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
publish_articles:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: increments/qiita-cli/actions/publish@v1
with:
qiita-token: ${{ secrets.QIITA_TOKEN }}
root: "."
重要な設定を順番に説明します。
6.1 自動実行のトリガー
on:
push:
branches:
- main
mainブランチにPushされたタイミングでワークフローが起動します。
つまり、ローカルから次のコマンドを実行すると、自動投稿処理が開始されます。
git push origin main
6.2 GitHubリポジトリの取得
- uses: actions/checkout@v7
with:
fetch-depth: 0
GitHub Actionsの実行環境にリポジトリをチェックアウトします。
fetch-depth: 0を指定することで、Gitの履歴をすべて取得します。
6.3 Qiitaへの自動投稿
- uses: increments/qiita-cli/actions/publish@v1
with:
qiita-token: ${{ secrets.QIITA_TOKEN }}
root: "."
Qiita公式のGitHub Actionを利用しています。
このActionの内部では、Qiita CLIを使用して以下のコマンドが実行されます。
qiita publish --all --root .
これにより、public/ディレクトリ内の投稿対象記事がQiitaに反映されます。
6.4 contents: writeの役割
permissions:
contents: write
Qiita CLIは投稿後に、記事のIDや更新日時をMarkdownファイルに反映します。
公式Actionは、その変更をGitHubへ自動コミットします。
この処理に必要なのがcontents: write権限です。
7. 記事を作成して自動投稿する
ここまでの設定が完了したら、実際に記事を作成します。
7.1 新規記事の作成
ローカルで以下を実行します。
npx qiita new sample-article
次のファイルが生成されます。
public/sample-article.md
ファイルを開き、記事のタイトルや本文を編集します。
---
title: "Qiita CLIの動作確認"
tags:
- QiitaCLI
- GitHubActions
private: false
updated_at: ""
id: null
organization_url_name: null
slide: false
ignorePublish: false
---
# はじめに
GitHub ActionsからQiitaへの
自動投稿を確認するための記事です。
実際には、CLIが生成したFront Matterを保持したまま編集します。
特に重要なのが以下の設定です。
id: null
ignorePublish: false
id: nullは、まだQiitaの記事IDが設定されていない状態です。
ignorePublish: falseは、Qiita CLIの投稿処理の対象にする設定です。
7.2 ローカルでプレビュー
以下のコマンドを実行します。
npx qiita preview
ブラウザから次のURLにアクセスします。
http://localhost:8888
Qiitaに近い表示で記事を確認できます。
なお、qiita previewはQiita上に存在する記事をローカルへ取得する動作も行うため、実行後にpublic/内のファイルが増えることがあります。
7.3 GitHubへPush
記事が完成したらコミットします。
git add public/sample-article.md
git commit -m "Add sample article"
git push origin main
これだけでGitHub Actionsが起動します。
GitHubのリポジトリからActionsタブを開くと、ワークフローの実行状況を確認できます。
正常終了すると、Qiitaへの投稿処理が完了します。
8. 投稿後になぜgit pullが必要なのか?
今回の仕組みで理解しておきたいのが、投稿後のGitHubとローカルの状態の違いです。
新規記事の作成時、Markdownには以下のように記載されています。
id: null
updated_at: ""
GitHub ActionsがQiitaへの投稿を実行すると、Qiita側で記事IDが発行されます。
その後、GitHub ActionsがMarkdownを更新します。
id: "発行された記事ID"
updated_at: "更新日時"
これらの変更はGitHub上でコミットされますが、ローカルPCにはまだ反映されていません。
そこで、次のコマンドを実行します。
git pull origin main
これにより、GitHub Actionsが更新した記事IDや更新日時をローカルにも反映できます。
記事IDは既存記事を識別するために重要です。
新規投稿後にid: nullのまま編集を続けると、重複投稿などの原因になり得ます。
そのため、新しい記事を初めて投稿した後は、次の編集を始める前にPullしておくことが重要です。
9. 既存記事をGitHubで管理する場合の注意点
Qiita CLIでは、すでにQiitaへ投稿している記事も取得できます。
npx qiita pull
このコマンドを実行すると、既存記事がMarkdownファイルとしてpublic/配下に保存されます。
例えば、以下のような構成になります。
public/
├── 00be4ec4f66953f88e75.md
├── 03b184ce60d60223c11f.md
├── sample-article.md
└── ...
既存記事には、Qiitaで発行済みの記事IDが設定されています。
id: 00be4ec4f66953f88e75
ignorePublish: false
ただし、ignorePublish: falseのままだと、qiita publish --allの投稿対象になります。
Qiita CLIには、ローカルの内容がQiita上の記事より古い可能性がある場合に投稿を停止する検証機能があります。
それでも、既存記事を意図せず自動更新することを避けたい場合は、投稿対象から明示的に除外すると安全です。
ignorePublish: true
この設定にすると、GitHubでファイルを管理しながら、Qiita CLIによる投稿処理から除外できます。
また、GitHubリポジトリをPublicにする場合、限定共有記事や公開したくない情報を含めないよう注意が必要です。
10. 実際に遭遇したエラーと対処方法
10.1 credentials.jsonが存在しない
GitHub Actionsの実行時、以下のエラーが発生しました。
Error: ENOENT: no such file or directory,
open '/home/runner/.config/qiita-cli/credentials.json'
これは、Qiita CLIが認証情報を取得できなかった際に発生することがあるエラーです。
今回の構成では、GitHub ActionsはQIITA_TOKEN環境変数を使用するため、通常は実行環境にcredentials.jsonを用意する必要はありません。
まず確認するべきなのは、GitHub Secretsです。
Repository
└── Settings
└── Secrets and variables
└── Actions
└── QIITA_TOKEN
Secretの名前や設定値に誤りがないか確認します。
修正後、GitHub Actionsの画面から失敗したジョブを再実行できます。
10.2 Repository not found
GitHubへPushする際、次のエラーが発生することがあります。
remote: Repository not found.
fatal: repository not found
リモートURLが正しいか確認します。
git remote -v
URLが間違っている場合は以下で修正します。
git remote set-url origin https://github.com/USERNAME/qiita-articles.git
リポジトリが作成済みであることや、アクセス権限も確認してください。
10.3 GitHub Actions実行後にローカルと差分が発生する
GitHub Actionsが記事IDや更新日時をコミットするため、ローカルとGitHubで差分が発生することがあります。
ローカルに未コミットの変更がない状態で、以下を実行して同期します。
git pull origin main
なお、PullはQiitaへ投稿するための操作ではありません。
あくまでGitHub上の更新内容をローカルへ反映するための操作です。
11. 今後の運用方法
最終的に、記事の執筆から投稿までの基本的な流れは以下になります。
作業開始時
git pull origin main
新規記事の作成
npx qiita new article-name
記事の編集
code public/article-name.md
プレビュー
npx qiita preview
自動投稿
git add public/article-name.md
git commit -m "Add new article"
git push origin main
GitHub Actionsが正常終了した後、必要に応じて次のコマンドで同期します。
git pull origin main
記事を更新する場合も、基本的には同様です。
また、GitHubのブランチ運用と組み合わせれば、記事をPull Requestでレビューしてから公開することも可能です。
まとめ
Qiita CLIとGitHub Actionsを組み合わせることで、記事の作成・管理・投稿をGitHub中心のワークフローに統一できました。
今回の構築で重要だった点は以下のとおりです。
- Qiita CLIを使用すると、記事をMarkdownファイルとして管理できる
- GitHub Actionsによって、Pushをきっかけに自動投稿できる
- GitHub Secretsを使用してアクセストークンを安全に管理する
-
ignorePublishによって記事ごとの投稿対象を制御できる - 投稿後に更新された記事IDをGitHubからPullすることで、ローカルとの整合性を維持できる
個人的には、単に投稿作業を自動化できることだけでなく、記事をGitでバージョン管理し、変更履歴を追跡できることが大きなメリットだと感じました。
今後は、GitHub Actionsを拡張してMarkdownの構文チェックやPull Request時の自動レビューなども組み込んでみたいと考えています。