Qiita CLI × GitHub Actions で、VS Code で書いた記事を push だけで投稿できるようにしました

みなさん、こんにちは！

Qiita の記事を、ブラウザのエディタではなく VS Code で書いて、GitHub に push するだけで投稿できるようにしました。この記事では、その環境の作り方と、実際に使ってみて「あれ？」と思ったポイントをまとめます。

Qiita CLI をこれから使ってみたい方や、記事を Git で管理したい方の参考になればうれしいです。

なぜブラウザで書かないのか

Qiita のブラウザエディタも便利なのですが、使い慣れた道具が使えないのが少し不便でした。VS Code なら拡張機能も使えますし、AI に手伝ってもらいながら書くのも簡単です。複数の記事を並べて見比べられるのも地味にうれしいところです。

そこで、公式の Qiita CLI を使って、記事を Markdown ファイルとして GitHub で管理することにしました。

ちなみに、この環境づくり自体も AI エージェントに頼んで作ってもらっています。そのあたりの話は後半で書きます。

全体の流れ

できあがった仕組みはこんな感じです。

VS Code で記事を書く（public/<slug>.md）
  ↓
npm run preview でローカル確認（http://localhost:8888）
  ↓
ignorePublish: false にして main に push
  ↓
GitHub Actions が Qiita に投稿
  ↓
投稿された記事の id などを、Actions がリポジトリにコミットして戻す

環境

• macOS
• Node.js v26.8.1（package.json の engines では 22.22.1 以上を指定）
• @qiita/qiita-cli 1.10.0

セットアップ手順

公式 README の手順をもとにした流れです。

1. Qiita CLI をインストールする

npm install @qiita/qiita-cli --save-dev
npx qiita version

2. 初期化する

npx qiita init

これで GitHub Actions のワークフロー（.github/workflows/publish.yml）、.gitignore、qiita.config.json が作られます。

qiita.config.json はプレビュー用の設定です。私の環境ではこうなっています。

{
  "includePrivate": false,
  "host": "localhost",
  "port": 8888
}

3. トークンを発行してログインする

Qiita のトークン発行画面で、read_qiita と write_qiita にチェックを入れてトークンを発行します。

npx qiita login

トークンを聞かれるので、発行したものを貼り付けます。トークンはリポジトリやコミットに含めないように気をつけてください。

4. npm scripts を用意する

毎回 npx qiita ... と打つのは長いので、package.json にまとめておきました。

"scripts": {
  "preview": "qiita preview",
  "new": "qiita new",
  "pull": "qiita pull",
  "publish": "qiita publish"
}

5. GitHub に Secret を登録する

GitHub のリポジトリで Settings → Secrets and variables → Actions を開き、QIITA_TOKEN という名前で、さきほどのトークンを登録します。Actions はこのトークンを使って投稿します。

6. ワークフローを確認する

私のリポジトリのワークフローはこちらです。qiita init が生成するテンプレートをもとに、AI に少し手を入れてもらっています。

.github/workflows/publish.yml

# Please set 'QIITA_TOKEN' secret to your repository
name: Publish articles

on:
  push:
    branches:
      - main
    paths:
      - "public/**.md"
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  publish_articles:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: increments/qiita-cli/actions/publish@v1.10.0
        with:
          qiita-token: ${{ secrets.QIITA_TOKEN }}
          root: "."

公式のテンプレートとの主な違いは次のとおりです。

• paths で、public/ 配下の Markdown が変わったときだけ動くようにしている
• 対象ブランチを main だけにしている
• Qiita CLI の Action を @v1.10.0 に固定している

permissions: contents: write は、投稿後に Actions が記事ファイルを更新してコミットするために必要です。

記事を書いて投稿するまで

記事を作る

npm run new -- qiita-cli-github-actions-setup

public/qiita-cli-github-actions-setup.md が作られます。中身はこんな感じです。

---
title: qiita-cli-github-actions-setup
tags:
  - ''
private: false
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: false
posting_campaign_uuid: null
agreed_posting_campaign_term: false
---
# new article body

ここで一つ目の注意点です。生成された直後は ignorePublish: false になっています。 このまま main に push すると、書きかけでも投稿されてしまいます。なので私は、ファイルを作ったらまず ignorePublish: true に変えてから書き始めるようにしています。

ついでに、private: true は「限定共有記事」の設定で、下書きという意味ではありません。下書きのつもりで private: true にしても、Qiita には投稿されてしまうので注意です。

プレビューする

npm run preview

ブラウザで http://localhost:8888 を開くと、Qiita とほぼ同じ見た目で確認できます。

push して投稿する

書き終わったら ignorePublish: false にして、main に push します。

git add public/qiita-cli-github-actions-setup.md
git commit -m "Qiita CLI の記事を追加"
git push origin main

GitHub の Actions タブを見ると、「Publish articles」のワークフローが動いているのが確認できます。

実際に使ってみて迷ったところ

プレビュー画面にも「投稿する」ボタンがある

最初に少し迷ったのがここです。npm run preview で開いた画面に「記事を投稿する」ボタンがあり、ここからも Qiita に投稿できます（公式 README にも書かれています）。

つまり、投稿する方法は大きく二つあります。

• プレビュー画面のボタン（または npx qiita publish）で、ローカルから直接投稿する
• GitHub に push して、Actions に投稿してもらう

どちらでも投稿はできますが、私は push して Actions で投稿する方法にそろえています。ボタンで投稿した場合も、記事ファイルの id などが書き換わるはずなので、そのファイルをコミットし忘れないように気をつけたほうがよさそうです。

投稿すると、Actions がコミットを追加してくる

Actions で投稿が終わると、github-actions[bot] から「Updated by qiita-cli」というコミットが追加されました。中身を見ると、記事の id と updated_at が書き込まれています。

 private: false
-updated_at: ''
-id: null
+updated_at: '2026-10-07T00:12:56+09:00'
+id: c2b6a17e9d2d683cabf8

この id があることで、次に push したときに新規投稿ではなく、同じ記事の更新として扱われるようです。

注意したいのは、このコミットはリモートにしかないということです。手元はリモートより一つ遅れた状態になるので、続けて作業する前に git pull しておきます。

git pull origin main

pull しないまま記事を直して push しようとすると、リモートに手元にないコミットがあるので push が拒否されます。そこで慌てて変更をまとめると、id が null に戻ってしまうこともありえます。そうなると、同じ記事を新しく投稿し直してしまうかもしれないので、「投稿したら pull」を習慣にしておくと安心です。

ローカルのファイルを消しても、Qiita の記事は消えない

public/ から Markdown ファイルを削除して push しても、Qiita 上の記事は削除されません。公式 README にも、Qiita CLI や Qiita Preview からは記事を削除できず、削除は Qiita のサイト上で行うと書かれています。

記事を消したいときは、Qiita にログインして、記事の画面から削除します。

AI と一緒に書くための工夫

せっかく VS Code で書けるようになったので、AI エージェントにも手伝ってもらいやすい形にしています。

AGENTS.md に執筆ルールをまとめる

リポジトリの直下に AGENTS.md を置き、AI 向けのルールをまとめました。たとえばこんな内容です。

• 文体は「です・ます」で、少し気軽な技術ブログの雰囲気にする
• 実際に経験していないことや、確認できていないことを事実のように書かない
• 新しい記事は npm run new で作り、すぐに ignorePublish: true にする
• 頼まれていない記事を公開したり、main に push したりしない

特に最後のルールは大事です。この仕組みだと「push = 投稿」なので、AI が気を利かせて push してしまうと、そのまま記事が公開されてしまいます。

記事作成の手順を skill にする

Claude Code では、よく使う作業の手順を skill としてまとめておけます。私は .claude/skills/qiita-new-article/SKILL.md に、記事を作るときの流れを書いています。

• 書く前に、題材や実際の体験を確認する
• npm run new で記事を作り、ignorePublish: true にする
• 記事の種類に合わせて構成を選ぶ
• 書き終わったらチェックリストで確認する

こうしておくと、「この内容で記事を書いて」と頼むだけで、決まった手順に沿って下書きを作ってくれます。実はこの記事の下書きも、この仕組みを使って AI と一緒に作りました。

もちろん、AI の書いた内容をそのまま信じるのではなく、手順やリンクは自分でも確認するようにしています。

さいごに

Qiita CLI と GitHub Actions を組み合わせることで、使い慣れた VS Code で書いて、push するだけで投稿できるようになりました。

ignorePublish の初期値や、Actions が追加するコミットなど、最初は少し戸惑うところもありました。同じように環境を作る方の参考になればうれしいです。