GitHubを使ってQiitaの記事を管理してみた

# はじめに

QiitaでGitHub Actionsを使って記事を管理する方法が掲載されていたので、試してみました。

https://qiita.com/Qiita/items/32c79014509987541130

https://github.com/increments/qiita-cli

```bash:
$ npx qiita new 20250215_newarticle
$ emacs public/20250215_newarticle.md
$ git add public/20250215_newarticle.md
$ git push
```

この記事を含む私のQiita記事はGitHub上で公開しています。

https://github.com/YasuhiroABE/qiita.com

# 下書きに登録されている記事の取り扱い

``npx qiita pull``を実行すると公開されている記事が全てダウンロードされます。

裏を返すと``下書き``に登録されている記事はqiita.com上に置かれたまま同期の対象とはなりません。

１度記事を投稿して公開すれば``npx qiita pull``で新規記事としてダウンロードできるはずなので、一応確認しておきます。

## 下書きに登録されている記事を公開してから同期を取る

記事を完成させて反映させてから同期させます。

```bash:
$ npx qiita pull
```

``git``コマンドで差分を確認します。

```bash:
$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   .gitignore
        modified:   Makefile

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        public/20250215_newarticle.md
        public/36dbe88619c258eb5b74.md

no changes added to commit (use "git add" and/or "git commit -a")
```

qiita.com上で投稿した記事はIDがそのままファイル名になってpublic/以下にコピーされています。

## 登録済みの記事をpushして変化がないか確認する

``public/36dbe88619c258eb5b74.md``をcommitして``git push``してみます。

この時の記事の更新時刻は``updated_at: '2025-02-15T21:18:13+09:00'``でした。

```bash:
$ git add public/36dbe88619c258eb5b74.md
$ git commit -m 'Added new published article public/36dbe88619c258eb5b74.md.'
$ git push
```

この後、``npx qiita pull``を実行しても特に変化はなく、既存の記事がGitHub Actionsで処理されることはありませんでした。

## 新規記事を投稿する

書きかけの ``public/20250215_newarticle.md`` を登録します。

```bash:
$ git add public/20250215_newarticle.md
$ git commit -m 'Added new article public/20250215_newarticle.md.'
$ git push
```

GitHubのプロジェクトページに移動して、Actionsタブから経過を見守ります。

30secで処理が完了したと記録されていますが、``git push``してからは2分ぐらいは経過していた印象です。

# 気がついたこと

## preview機能が秀逸

ファイルの更新に応じてpreviewも更新されるためQiita公式サイトで編集するのと大きな違いを感じませんでした。

画像ファイルのアップロードはpreviewページのリンクを辿って公式サイトで手動で管理しなければいけない点は少し面倒ですが、クリップボードからのコピーができてMarkdown形式でURLのコピーが出来るので、これは大きな障害ではないと思っています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/78296/304c6df0-e6b9-4167-9e3d-79a838823dd7.png)

## 内容の重複するファイルが作成されてしまう

``npx qiita new``で作成したファイルを``git add/commit/push``すると、ActionsによってQiitaに記事が登録されます。

:::note
しばらくこの現象を追っていましたが、GitHub Actionsでは``npx qiita publish --all``相当の処理が行われているだけなので、原理的にこれはおかしな現象でした。

いまのところ、この現象は再発していないので、このセクションの内容は無視してもらえればと思います。
:::

この後に``npx qiita pull``を実行するとGitHub ActionsからQiita側に登録された記事が``public/87881ee04e6052acafee.md``のようなファイル名で新しく作成されます。

こちらで適当に作成したファイル名とQiita側で統一的にIDで管理されているファイルの2つが出来るのは当然ですが、どちらを編集するべきか、考えなければいけないという点では少し悩ましいです。

GitHub側から全てのファイルをpushして、``npx qiita pull``を止めれば良いというのは、revalidationが出来なくなる点で問題があります。

これは結構悩ましく、投稿したことでIDが確定するのでファイル名は予測不可能です。

後から``git mv``でIDのファイル名に変更するのが最善手のように考えています。

## git pushをすると常にコンフリクトが発生してしまう

しばらく使ってみるとGitHub Actionsがgithub.com側のmainブランチを更新するので、``git pull``を実行すると常にmergeが動いてしまうことに気がつきました。

差分を確認すると``updated_at:``行が変化しただけですね。

```diff:
diff --git a/public/87881ee04e6052acafee.md b/public/87881ee04e6052acafee.md
index 8e6c8b1..53bd9eb 100644
--- a/public/87881ee04e6052acafee.md
+++ b/public/87881ee04e6052acafee.md
@@ -4,7 +4,7 @@ tags:
   - GitHub
   - qiita-cli
 private: false
-updated_at: '2025-02-15T23:38:56+09:00'
+updated_at: '2025-02-15T23:47:08+09:00'
 id: 87881ee04e6052acafee
 organization_url_name: null
 slide: false
```

このため``git push``した後は、Actionsの処理が終わってから``git pull`を実行するようにしています。

:::note
ファイルを登録する際には``npx qiita publish``で投稿してから変更分をGitHub Actionsに処理させる方法が良さそうです。
:::

## 更新したいファイルを探すのが少し面倒

Webページから検索するのも、grepコマンドを使うのもあまり大差ないのですが、せっかくgitでファイル単位で管理できるようになってもファイル名は手掛りにならないのは少し物足りなく感じます。

## 更新履歴のコメントが反映されない

Gitのコミットログがそのまま反映されても困るなぁと思いつつ、公式サイトの更新履歴には何も記載されていませんでした。

編集履歴を確認する人もそんなにいないかもしれませんし、自分が分かれば良いという点ではgitコマンドで差分が確認できるから良いよね、とは思いつつ、一言ぐらいは何か残しておきたい気もします。

# さいごに

丸1日、qiita-cliを使ってみましたが、総じて問題はないのかなと思います。

無理にGitHubと連携させなくても、``npx qiita new/publish`` と``git``コマンドを連携させても十分な気もしますし、この点は好みで使い方を決められるという点では良いのかもしれません。

また、GitHub Actionsに触れるための最初の一歩としても良い機会かもしれません。

[.github/workflows/publish.yml](https://github.com/YasuhiroABE/qiita.com/blob/main/.github/workflows/publish.yml)と[increments/qiita-cli/actions/publish@v1](https://github.com/increments/qiita-cli/blob/main/actions/publish/action.yml)を読めば、GitHub Actionsが何をやっているのか、何となく分かると思います。