0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

GitHubにPushするだけでQiitaへ自動投稿する方法【Qiita CLI × GitHub Actions】

0
Last updated at Posted at 2026-11-12

はじめに

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の認証が必要です。

まず、以下のページでアクセストークンを発行します。

Qiita アクセストークン発行ページ

権限には以下の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中心のワークフローに統一できました。

今回の構築で重要だった点は以下のとおりです。

  1. Qiita CLIを使用すると、記事をMarkdownファイルとして管理できる
  2. GitHub Actionsによって、Pushをきっかけに自動投稿できる
  3. GitHub Secretsを使用してアクセストークンを安全に管理する
  4. ignorePublishによって記事ごとの投稿対象を制御できる
  5. 投稿後に更新された記事IDをGitHubからPullすることで、ローカルとの整合性を維持できる

個人的には、単に投稿作業を自動化できることだけでなく、記事をGitでバージョン管理し、変更履歴を追跡できることが大きなメリットだと感じました。

今後は、GitHub Actionsを拡張してMarkdownの構文チェックやPull Request時の自動レビューなども組み込んでみたいと考えています。

参考資料

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?