技術記事のサンプルコードをGitHub ActionsでCI検証して「動作確認済み」を担保する

課題

技術記事の「動作確認済み」は、書いた瞬間しか保証していません。依存ライブラリやランタイムの更新で、あとから動かなくなります。読む側はつらいし、書く側も自分の過去記事が同じ疑いを受けます。

結論

記事のサンプルコードを examples/ に独立プロジェクトとして置き、front matter に検証方法を宣言して、GitHub Actions で定期実行し、結果を記事に書き戻します。

手順

1. サンプルコードを独立して動く形で配置する

examples/ci-verify/
├── package.json        # "type": "module", "test": "node --test"
├── status-label.js
└── status-label.test.js

2. 記事の front matter に検証情報を書く

tested_path: "examples/ci-verify"
test_command: "node --test"
ci_status: ""        # CIが書き戻す
ci_checked_at: ""
ci_run_url: ""

3. 検証スクリプトで front matter を読み、テストを実行する

各記事の tested_path / test_command を読み、そのディレクトリでコマンドを実行。終了コードで状態を判定します。

code = run(test_command, target)
if code is None:
    return "error"
return "passing" if code == 0 else "failing"

passing / failing / error / skipped を ci_status として記事に書き戻します。

4. GitHub Actions で回す

on:
  schedule:
    - cron: '0 18 * * 0'   # 毎週日曜18:00 UTC
  push:
    branches: [ main ]
    paths:
      - 'examples/**'
  workflow_dispatch:

permissions:
  contents: write

注意点

• 書き戻しコミットでCIが再帰しないよう、コミットメッセージにマーカー（例: [ci-verify]）を付ける
• front matter を書き換えるので GITHUB_TOKEN に contents: write 権限が必要
• 外部API・認証が絡むコードはCIで安定しにくい。無理に載せず手動確認に回す
• コードのない記事は tested_path を空にして対象外（skipped）にする
• schedule を入れないと「依存更新で壊れた」を検知できない（ここが一番効く）