対象読者
Python を利用したことがあるエンジニア、GitHub Actions を利用したことがあるエンジニア、Qiita への投稿を効率化したい方

動作確認環境 / 前提条件

macOS Ventura 13.6.3

Python 3.11.5

GitHub アカウント

Qiita API v2 の理解（公式ドキュメント参照）

以前の記事「Python × GitHub Actions で始める！Qiita 自動投稿パイプライン構築術」の内容を理解していること

この記事で得られること

Qiita 記事投稿を自動化する Python スクリプトの構築方法

GitHub Actions を利用した CI/CD パイプラインの構築方法

自動化パイプライン構築におけるハマりどころと、その解決策

実際に躓いたポイントと解決策

1. Gemini APIのモデル名エラー

問題:

404 models/gemini-1.5-flash is not found for API version v1beta

原因:

設定ファイルでgemini-1.5-flashを指定していたが、実際に利用可能なモデルはmodels/gemini-2.0-flashだった
Google Gemini APIは定期的にモデル名が更新される

解決策:

# 利用可能なモデルを確認
models = [m for m in genai.list_models() 
          if 'generateContent' in m.supported_generation_methods]
# 結果: models/gemini-2.0-flash, models/gemini-2.5-flash など

# 設定ファイルを更新
{
  "api": {
    "gemini": {
      "model": "models/gemini-2.0-flash"  # models/プレフィックスが必要
    }
  }
}

学んだこと: APIの仕様変更に備えて、利用可能なモデルを動的に確認する仕組みを追加すべき

2. WindowsコンソールのUnicode文字表示エラー

問題:

UnicodeEncodeError: 'cp932' codec can't encode character '✓' in position 0

原因:

WindowsのPowerShellでは、Unicode文字（✓、⚠、✗）がデフォルトのエンコーディング（cp932）で表示できない

解決策:

# Unicode文字を通常の文字に置き換え
print(f"[OK] 処理が完了しました")  # ✓ → [OK]
print(f"[WARN] 警告メッセージ")    # ⚠ → [WARN]
print(f"[ERROR] エラーが発生")     # ✗ → [ERROR]

学んだこと: クロスプラットフォーム対応では、Unicode文字の使用を避けるか、エンコーディングを明示的に設定する

3. Qiita APIのタグ数制限による403エラー

問題:

HTTPエラー: 403 - {'message': 'Forbidden', 'type': 'forbidden'}

原因:

動的タグ生成で9個のタグを生成していたが、Qiita APIはタグを最大5個までしか受け付けない
APIドキュメントを確認せずに実装していた

解決策:

# タグを5個に制限
if len(tags) > 5:
    print(f"[WARN] タグが{len(tags)}個ありますが、Qiita APIの制限により5個に制限します")
qiita_tags = [{"name": tag} for tag in tags[:5]]

学んだこと:

APIの仕様を事前に確認する重要性
エラーメッセージが不十分な場合、リクエスト内容を詳細にログ出力して原因を特定する

4. LLMプロンプトの設計ミス

問題:

タイトル案を3つ生成していたが、実際のタイトルが「使用例」になってしまった
パース処理でタイトルが正しく抽出できなかった

原因:

プロンプトで「タイトル案（3つ）」を指示していたが、実際のタイトルを明確に指定していなかった
パース処理がタイトル案セクションをスキップできていなかった

解決策:

# プロンプトの修正
**重要**: 記事の最初の行に、実際に使用するタイトルを`# `で始まるMarkdownの見出し形式で記述してください。

タイトル案は不要です。最初の`# `行がそのまま記事のタイトルとして使用されます。

# パース処理の改善
skip_title_section = False
for line in lines:
    # タイトル案セクションを検出してスキップ
    if "タイトル案" in line:
        skip_title_section = True
        continue
    
    # 最初の`# `で始まる行をタイトルとして取得
    if not found_main_title and line.startswith("# "):
        title = line.replace("# ", "").strip()
        found_main_title = True

学んだこと:

LLMへのプロンプトは明確で具体的な指示が必要
出力形式を厳密に指定することで、パース処理を簡潔にできる

5. エラーハンドリングの不足

問題:

403エラーが発生した際、原因が特定しづらかった
デバッグ情報が不足していた

解決策:

# デバッグ情報の追加
print(f"[DEBUG] アクセストークン: {token_preview}")
print(f"[DEBUG] リクエストURL: {self.base_url}/items")
print(f"[DEBUG] ペイロード: title={title[:50]}, tags={len(tags)}個")
print(f"[DEBUG] レスポンスステータス: {response.status_code}")

# エラーメッセージの改善
if e.response.status_code == 403:
    error_msg += "

考えられる原因:"
    error_msg += "
- アクセストークンのスコープが不足しています"
    error_msg += "
- タグ数が5個を超えています（Qiita APIの制限）"

学んだこと:

エラー発生時には、リクエスト内容とレスポンスを詳細にログ出力する
よくあるエラーについては、解決策を提示する

工夫したポイント

1. プロンプト管理システム

プロンプトをMarkdownファイルとして管理し、変数置換に対応：

# data/prompts/article_generation_prompt.md
トピック: {topic}
リサーチ結果: {research_results}
過去の投稿: {past_articles_summary}

# 使用例
prompt = template.format(
    topic=selected_topic,
    research_results=research_results,
    past_articles_summary=past_articles_summary
)

メリット:

プロンプトの変更が容易
バージョン管理がしやすい
複数のプロンプトを管理できる

2. 過去の投稿参照機能

過去のQiita投稿を取得し、ストーリー性のある記事を生成：

# 過去の投稿を取得
fetcher = QiitaFetcher()
items = fetcher.fetch_all_my_items(days_back=180)

# 記事生成時に参照
past_articles_summary = qiita_items_manager.get_items_summary(limit=10)

メリット:

連続性のある記事シリーズを構築できる
読者が「次も読みたい」と思える内容になる
過去の投稿への参照リンクを自動生成

3. 動的タグ生成

記事内容に応じてLLMが自動的にタグを生成：

def generate_dynamic_tags(title: str, content: str) -> List[str]:
    # 記事のタイトルと内容を分析してタグを生成
    # 言語・ツール系、目的・行為ベース、プラットフォーム系など
    # カテゴリから適切なタグを選ぶ

メリット:

記事内容に最適なタグが自動生成される
手動でのタグ付けが不要
タグの漏れを防げる

4. モジュール化とエラーハンドリング

各機能を独立したモジュールに分割し、エラーハンドリングを強化：

# 各モジュールが独立して動作
- research/collector.py      # リサーチ機能
- generator/article_generator.py  # 記事生成
- publisher/qiita_publisher.py    # 投稿機能
- storage/article_manager.py      # 記事管理

メリット:

テストが容易
機能の追加・変更が容易
エラーの影響範囲を限定できる

参考文献

Qiita API v2 ドキュメント
- タグの制限（最大5個）などの仕様を確認
Google Gemini API ドキュメント
- 利用可能なモデル一覧とAPIの使い方
Python requests ライブラリ
- HTTPリクエストのエラーハンドリング方法
python-dotenv ドキュメント
- 環境変数の管理方法
Qiita API を利用した記事投稿の実装例
- アクセストークンの取得方法と投稿の実装

まとめ

今回の開発を通じて、以下の点を学びました：

APIの仕様を事前に確認する重要性: タグ数の制限など、APIの制約を理解しておく
エラーハンドリングの重要性: デバッグ情報を充実させ、原因特定を容易にする
プロンプト設計の重要性: LLMへの指示は明確で具体的にする
クロスプラットフォーム対応: Unicode文字の使用に注意する
モジュール化の重要性: 機能を分割し、テストとメンテナンスを容易にする

これらの経験を活かして、より堅牢なシステムを構築していきたいと思います。

🧭 導入：背景・課題・なぜ重要か

「記事書くの、めんどくさい…」

エンジニアなら誰しも一度は思ったことがあるのではないでしょうか？特に Qiita のような技術情報共有プラットフォームでは、継続的なアウトプットが重要だと分かっていても、ついつい後回しにしてしまいがちです。

以前の記事「Python × GitHub Actions で始める！Qiita 自動投稿パイプライン構築術」では、Qiita への記事投稿を自動化する基本的なパイプラインを構築しました。しかし、実際に運用してみると、いくつかの課題が見えてきました。

ローカル環境との差異: ローカルで動いていたスクリプトが GitHub Actions 上で動かない…あるあるですよね。
エラーハンドリングの甘さ: エラーが発生した場合に、どこが原因なのか特定しにくい…デバッグ地獄！
API レート制限: Qiita API のレート制限に引っかかって投稿が失敗する…焦る！

これらの課題を解決し、より安定した自動投稿パイプラインを構築するために、試行錯誤した過程を共有したいと思います。今回の記事では、これらの “あるある” な課題 に焦点を当て、具体的な解決策と、さらに効率的な運用方法を紹介します。

📘 トピックの概要（専門外にも分かる説明）

今回のテーマは、Qiita 記事の自動投稿パイプライン構築 です。

パイプライン とは、一連の処理を自動的に実行する仕組みのことです。今回の場合は、以下のような流れになります。

記事の Markdown ファイルを GitHub リポジトリに push
GitHub Actions が push を検知して自動的にスクリプトを実行
スクリプトが Qiita API を利用して記事を投稿

このパイプラインを構築することで、記事を書いたら GitHub に push するだけで Qiita に投稿されるようになります。

今回の記事では、特に以下の点に焦点を当てて解説します。

環境構築: GitHub Actions 上で Python スクリプトを実行するための環境構築
エラーハンドリング: エラーが発生した場合に、原因を特定しやすくするための工夫
レート制限対策: Qiita API のレート制限に引っかからないようにするための対策

🔧 技術的な仕組み・実装・アーキテクチャ

今回のパイプラインは、主に以下の要素で構成されています。

Python スクリプト: Qiita API を利用して記事を投稿するスクリプト
GitHub Actions: GitHub の CI/CD サービス。push をトリガーにしてスクリプトを実行
Qiita API: Qiita の記事投稿 API

Python スクリプト は、Markdown ファイルを読み込み、Qiita API に必要な情報を整形してリクエストを送信します。

GitHub Actions は、.github/workflows ディレクトリに YAML ファイルを配置することで、様々なイベントをトリガーにして処理を実行できます。今回は、push イベントをトリガーにして、Python スクリプトを実行します。

Qiita API は、記事の投稿、更新、削除などを行うための API です。API を利用するためには、事前に Qiita でアクセストークンを取得する必要があります。

メリット・デメリット

メリット:

記事投稿の手間を大幅に削減できる
継続的なアウトプットを促進できる
チームでの記事作成を効率化できる

デメリット:

初期構築に手間がかかる
API のレート制限に注意する必要がある
スクリプトのメンテナンスが必要

ハマりポイント・注意点

環境変数: GitHub Actions 上で環境変数を設定する必要がある
依存関係: 必要な Python ライブラリを requirements.txt に記述する必要がある
エラーハンドリング: エラーが発生した場合に、原因を特定できるようにログを出力するようにする

🧪 実践編：動くコード／コマンド例

1. 環境構築

まず、必要な Python ライブラリをインストールします。

# 必要なライブラリをインストール
pip install requests python-dotenv

次に、GitHub リポジトリに .github/workflows/qiita_post.yml ファイルを作成し、以下の内容を記述します。

name: Qiita Post

on:
  push:
    branches:
      - main

jobs:
  qiita_post:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python 3.11
        uses: actions/setup-python@v3
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run Qiita Post Script
        env:
          QIITA_ACCESS_TOKEN: ${{ secrets.QIITA_ACCESS_TOKEN }}
        run: python qiita_post.py

QIITA_ACCESS_TOKEN は、GitHub リポジトリの Secrets に登録する必要があります。

2. Python スクリプト

次に、qiita_post.py ファイルを作成し、以下の内容を記述します。

import os
import requests
from dotenv import load_dotenv

load_dotenv()

QIITA_ACCESS_TOKEN = os.environ.get("QIITA_ACCESS_TOKEN")
QIITA_API_ENDPOINT = "https://qiita.com/api/v2/items"

def post_to_qiita(markdown_file_path):
    """Qiita に記事を投稿する関数"""
    try:
        with open(markdown_file_path, "r", encoding="utf-8") as f:
            markdown_content = f.read()

        # タイトルを抽出 (最初の行が # で始まる場合)
        lines = markdown_content.splitlines()
        title = lines[0].replace("# ", "") if lines and lines[0].startswith("# ") else "No Title"

        # Markdown ファイルから必要な情報を抽出
        body = markdown_content
        tags = extract_tags(markdown_content) # タグを抽出する関数は別途定義

        # Qiita API に投稿
        headers = {
            "Authorization": f"Bearer {QIITA_ACCESS_TOKEN}",
            "Content-Type": "application/json",
        }
        data = {
            "title": title,
            "body": body,
            "tags": [{"name": tag} for tag in tags],
            "private": False,  # 公開設定
        }
        response = requests.post(QIITA_API_ENDPOINT, headers=headers, json=data)

        # レスポンスを確認
        response.raise_for_status()  # エラーがあれば例外を発生
        print("記事の投稿に成功しました！")
        print(f"投稿URL: {response.json()['url']}")

    except requests.exceptions.RequestException as e:
        print(f"APIリクエストエラー: {e}")
    except FileNotFoundError:
        print(f"ファイルが見つかりません: {markdown_file_path}")
    except Exception as e:
        print(f"予期せぬエラーが発生しました: {e}")

def extract_tags(markdown_content):
    """Markdown ファイルからタグを抽出する関数（例）"""
    # 簡単な例として、ファイル名からタグを生成
    # 実際には、Markdown の内容を解析してタグを抽出する処理を実装する
    return ["

生成日時: 2025-12-05 17:07:33
ステータス: draft
タグ: Qiita, 環境構築, Python, エンジニア向け, GitHubActions, スクリプト, CI/CD, Tips, 自動化, パイプライン