【Qiita CLI × GitHub Actions】記事管理をGit管理に移行した運用設計

Posted at 2026-04-30

はじめに

本記事は以下の公式ドキュメントをベースに、実際の運用設計をまとめたものです。
セットアップの詳細や最新情報は公式を合わせて参照してください。

これまでQiitaの記事はブラウザ上のエディタで書いていた。それ自体は問題ないのだが、以下のような課題があった。

記事の変更履歴が残らない
執筆中の下書きがQiita上にしか存在しない
複数記事の管理が煩雑になりやすい

これを解決するために、Qiita-CLI + GitHub + GitHub Actionsを使った記事管理フローを構築した。本記事ではその構成と運用設計をまとめる。

構成概要

ローカルで記事を書く（Markdown）
　↓
featureブランチにcommit & push
　↓
GitHubでPull Request作成
　↓
mainにマージ
　↓
GitHub Actionsが自動起動
　↓
Qiitaに自動投稿・更新

ポイントはPRのマージをQiita投稿のトリガーにしている点だ。これにより「mainにある記事＝Qiitaに公開されている記事」となる。

セットアップ

1. qiita-cliの初期化

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

初期化すると以下のファイルが生成される。

my-qiita-articles/
├── .github/
│   └── workflows/
│       └── publish.yml   # GitHub Actionsワークフロー（自動生成）
├── public/               # 記事のMarkdownファイルを置く場所
├── .gitignore
├── package.json
└── qiita.config.json

publish.ymlはqiita-cliが自動生成するので、基本的にそのまま使える。

2. GitHubリポジトリの作成とpush

GitHubで新しいリポジトリを作成し（qiita-articlesなど）、ローカルからpushする。

git init
git add .
git commit -m "initial commit"
git remote add origin https://github.com/<ユーザー名>/qiita-articles.git
git push -u origin main

注意: Personal Access Tokenにはrepoスコープに加えて**workflowスコープ**が必要。これがないと.github/workflows/publish.ymlのpushで弾かれる。

3. QiitaトークンをGitHub Secretsに登録

Qiitaのアクセストークンを取得する。

https://qiita.com/settings/tokens/new にアクセス
スコープでread_qiitaとwrite_qiitaにチェック
トークンを発行してコピー

次にGitHubリポジトリのSecretsに登録する。

リポジトリの Settings → Secrets and variables → Actions
「New repository secret」
Name: QIITA_TOKEN、Value: コピーしたトークン

4. GitHub Actionsワークフローの確認

npx qiita initで自動生成された.github/workflows/publish.ymlの内容は以下の通り。

name: Publish articles

on:
  push:
    branches:
      - main
      - master
  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@v4
        with:
          fetch-depth: 0
      - uses: increments/qiita-cli/actions/publish@v1
        with:
          qiita-token: ${{ secrets.QIITA_TOKEN }}
          root: "."

mainへのpushをトリガーにQiitaへ投稿する設定になっている。

運用フロー

新しい記事を書くとき

# 作業前にmainを最新化
git pull origin main

# featureブランチを作成
git checkout -b feature/記事タイトル

# 記事ファイルを作成
npx qiita new 記事ファイル名

# 執筆...

# commitしてpush
git add .
git commit -m "add: 記事タイトル"
git push origin feature/記事タイトル

GitHubでPull Requestを作成し、mainにマージするとActionsが起動してQiitaに投稿される。

ヘッダの設定

npx qiita newで生成される記事のヘッダは以下の通り。

---
title: <記事ファイル名> ← qiita new で指定したファイル名
tags:
  - ''
private: false
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: false
---

各項目の意味は以下の通り。

項目	説明
`private: false`	全体公開
`private: true`	限定共有公開

注意: tagsが空だと投稿時にエラーになる。必ず1つ以上設定すること。

既存記事を更新するとき

git pull origin main
git checkout -b feature/記事タイトル-update

# 記事を編集...

git add .
git commit -m "update: 記事タイトル"
git push origin feature/記事タイトル-update

同様にPRを作成してmainにマージすれば自動更新される。

ハマりどころ

Personal Access TokenのWorkflowスコープ

GitHub ActionsのワークフローファイルをpushするにはPATにworkflowスコープが必要。repoスコープだけでは以下のエラーが出る。

refusing to allow a Personal Access Token to create or update workflow
`.github/workflows/publish.yml` without `workflow` scope

トークン発行時にrepoとworkflowの両方にチェックを入れること。

GitHub ActionsのコミットによるConflict

Actionsが実行されるとQiitaから記事情報（idなど）を取得してGitHubリポジトリに書き戻す。そのためローカルとリモートで差分が生じることがある。作業前に必ずgit pull origin mainを実行する習慣をつけておくと防げる。

publicディレクトリ内のgit管理問題

npx qiita initをpublic/ディレクトリ内で実行してしまうと、ネストされたgitリポジトリが生成されてしまう。プロジェクトルート（qiita.config.jsonがある階層）で初期化すること。

不精な人向けの運用例

ここまで説明してきたフローは「ちゃんとやる人向け」。正直、ブランチを切ってPRを出してマージして…という手順は、記事を書く頻度が低いと忘れる。

そういう人にはWebUIで執筆・投稿しつつ、GitHubはバックアップとして使う運用をおすすめする。

設定変更

publish.ymlのonを以下のように変更する。これでGitHubへpushしてもQiitaには何も起きなくなる。

on:
  workflow_dispatch:  # 手動実行のみ

日常の流れ

Qiita WebUIで普通に執筆・投稿する
記事を書いたタイミングで以下を実行してGitHubにバックアップする

cd my-qiita-articles
npx qiita pull
git add .
git commit -m "chore: sync articles"
git push

ブランチは不要、mainへ直接コミットでOK。npx qiita pullでQiita上の最新記事をローカルに取り込んでからpushするだけなのでコンフリクトも起きにくい。

注意点

WebUIで編集した後は必ずnpx qiita pullしてからpushする。これを怠るとGitHub上の内容が古くなる
バックアップの頻度は「記事を投稿したタイミング」や「週1回」など自分でルールを決めておくと忘れにくい、かもしれない。

手順が少ないほど続く。完璧な運用より、続く運用の方が価値がある。

おわりに

この構成を整えてよかった点をまとめると、

記事の変更履歴がGitHubで追える
PRのマージという明確なトリガーで公開されるので意図しない公開が防げる
ローカルのエディタで快適に執筆できる

ガッツリ運用したい人はfeatureブランチ＋PR、手間をかけたくない人はWebUI＋バックアップと、自分のスタイルに合わせて使い分けてほしい。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up