invoking-github

GitHub の呼び出し

Claude.ai のチャットから GitHub リポジトリをプログラムで操作できます。ファイルの読み込み、変更のコミット、PR の作成、セッションをまたいだ状態の保持が可能です。

このスキルを使う場面

不要な場面：

• Claude Code 環境（ネイティブの git コマンドを使用してください）
• リポジトリへの読み取り専用アクセス（GitHub の UI または API を直接使用してください）

クイックスタート

前提条件

GitHub Personal Access Token を作成し、プロジェクトのナレッジに追加します。

1. https://github.com/settings/tokens にアクセスします
2. 新しいトークンを作成します（classic または fine-grained）
3. 必要なスコープ：repo（公開リポジトリのみの場合は public_repo）
4. Claude.ai で、プロジェクトのナレッジに追加します。
   • タイトル：GITHUB_API_KEY
   • 内容：トークン（例：ghp_abc123...）

単一ファイルのコミット

from invoking_github import commit_file

result = commit_file(
    repo="username/repo-name",
    path="README.md",
    content="# Updated README\n\nNew content here...",
    branch="main",
    message="Update README with new instructions"
)

print(f"Committed: {result['commit_sha']}")

ファイルの読み込み

from invoking_github import read_file

content = read_file(
    repo="username/repo-name",
    path="config.json",
    branch="main"
)

print(content)

一括コミット（複数ファイル）

from invoking_github import commit_files

files = [
    {"path": "src/main.py", "content": "# Python code..."},
    {"path": "README.md", "content": "# Updated docs..."},
    {"path": "tests/test.py", "content": "# Tests..."}
]

result = commit_files(
    repo="username/repo-name",
    files=files,
    branch="feature-branch",
    message="Add new feature implementation",
    create_branch_from="main"  # Create branch if it doesn't exist
)

print(f"Committed {len(files)} files: {result['commit_sha']}")

プルリクエストの作成

from invoking_github import create_pull_request

pr = create_pull_request(
    repo="username/repo-name",
    head="feature-branch",
    base="main",
    title="Add new feature",
    body="## Changes\n- Implemented feature X\n- Updated docs\n- Added tests"
)

print(f"PR created: {pr['html_url']}")

主な関数

read_file()

リポジトリからファイルを読み込みます。

read_file(
    repo: str,           # "owner/name"
    path: str,           # "path/to/file.py"
    branch: str = "main" # Branch name
) -> str

戻り値：ファイルの内容を文字列として返します
例外：ファイルが見つからない場合、またはアクセスが拒否された場合に GitHubAPIError を発生させます

commit_file()

単一ファイルをコミットします（作成または更新）。

commit_file(
    repo: str,                      # "owner/name"
    path: str,                      # "path/to/file.py"
    content: str,                   # New file content
    branch: str,                    # Target branch
    message: str,                   # Commit message
    create_branch_from: str = None  # Create branch from this if doesn't exist
) -> dict

戻り値：commit_sha、branch、file_path を含む Dict
例外：競合または認証エラーが発生した場合に GitHubAPIError を発生させます

commit_files()

複数のファイルを1つのコミットにまとめます。

commit_files(
    repo: str,                      # "owner/name"
    files: list[dict],              # [{"path": "...", "content": "..."}]
    branch: str,                    # Target branch
    message: str,                   # Commit message
    create_branch_from: str = None  # Create branch from this if doesn't exist
) -> dict

戻り値：commit_sha、branch、files_committed を含む Dict
例外：失敗した場合に GitHubAPIError を発生させます

注：効率化のために Git Trees API を使用し、すべてのファイルをアトミックにコミットします。

create_pull_request()

プルリクエストを作成します。

create_pull_request(
    repo: str,      # "owner/name"
    head: str,      # Source branch (your changes)
    base: str,      # Target branch (where to merge)
    title: str,     # PR title
    body: str = ""  # PR description (supports markdown)
) -> dict

戻り値：number、html_url、state を含む Dict
例外：ブランチが無効な場合、または PR がすでに存在する場合に GitHubAPIError を発生させます

認証情報の設定

このスキルには GitHub Personal Access Token が必要です。設定方法は2つあります。

方法1：プロジェクトのナレッジ（推奨）

Claude.ai のチャットを利用するユーザー（モバイル／ウェブ）に最適です。

1. https://github.com/settings/tokens でトークンを作成します
2. Claude.ai のプロジェクト設定から、プロジェクトのナレッジに追加します
3. GITHUB_API_KEY というタイトルのドキュメントを作成します
4. 内容にトークンを貼り付けます

必要な権限：

• Classic トークン：repo スコープ
• Fine-grained トークン：リポジトリの権限 → Contents（読み取り／書き込み）および Pull requests（読み取り／書き込み）

方法2：API Credentials スキル（代替手段）

代わりに、認証情報をまとめたファイルを使用できます。

1. プロジェクトのナレッジに API_CREDENTIALS.json を作成します
2. 次の内容を追加します：{"github_api_key": "ghp_your-token-here"}

Iterating スキルとの連携

セッションをまたいだ継続性のために、DEVLOG.md を GitHub に自動保存します。

# In your DEVLOG update function
from invoking_github import commit_file
from pathlib import Path

def update_devlog_with_sync(data, repo="user/project", branch="devlog"):
    """Update DEVLOG.md locally and sync to GitHub"""

    # Update local DEVLOG
    update_devlog(data)  # Your existing function

    # Auto-sync to GitHub
    try:
        devlog_content = Path("DEVLOG.md").read_text()

        result = commit_file(
            repo=repo,
            path="DEVLOG.md",
            content=devlog_content,
            branch=branch,
            message=f"DEVLOG: {data['title']}",
            create_branch_from="main"
        )

        print(f"✓ DEVLOG synced to GitHub ({repo}:{branch})")
        return result

    except Exception as e:
        print(f"⚠ DEVLOG sync failed: {e}")
        # Continue anyway - local DEVLOG.md still updated
        return None

メリット：

• セッションの進捗を自動バックアップ
• デバイスをまたいで開発ログにアクセス可能
• 判断と進捗の Git 履歴を保持
• プロジェクトのナレッジへの手動コピー＆ペーストが不要

完全なパターンについては、references/iterating-integration.md を参照してください。

エラー処理

すべての関数は、内容を説明するメッセージとともに GitHubAPIError を発生させます。

from invoking_github import commit_file, GitHubAPIError

try:
    result = commit_file(
        repo="user/repo",
        path="file.py",
        content="...",
        branch="main",
        message="Update"
    )
except GitHubAPIError as e:
    if e.status_code == 404:
        print("Repository or branch not found")
    elif e.status_code == 401:
        print("Authentication failed - check your token")
    elif e.status_code == 403:
        print("Access denied - check token permissions")
    elif e.status_code == 409:
        print("Conflict - file was modified since last read")
    else:
        print(f"GitHub API error: {e}")

よくあるエラー：

• 404：リポジトリ、ブランチ、またはファイルが見つかりません
• 401/403：トークンが無効、または権限が不足しています
• 409：マージ競合（ファイルが同時に変更されました）
• 422：検証エラー（ブランチ名が無効など）
• レート制限：リクエストが多すぎます（再試行する前に待機してください）

ベストプラクティス

1. 内容がわかるコミットメッセージを使う

   • 悪い例："Update files"
   • 良い例："Add authentication middleware and update user routes"

2. 可能な場合はコミットをまとめる

   • 関連する変更には commit_files() を使用します
   • 単一のアトミックなコミットにすると、Git の履歴がすっきりします

3. フィーチャーブランチを作成する

   • main に直接コミットしないでください
   • create_branch_from="main" パラメーターを使用します
   • レビュー用に PR を作成します

4. トークンを安全に管理する

   • 最小限のスコープを持つ fine-grained トークンを使用します
   • 有効期限を設定します
   • 定期的にローテーションします
   • トークンをリポジトリにコミットしないでください

高度な使い方

条件付きコミット

ファイルの内容が変更された場合にのみコミットします。

from invoking_github import read_file, commit_file, GitHubAPIError

try:
    current_content = read_file(repo, path, branch)
    if current_content != new_content:
        commit_file(repo, path, new_content, branch, "Update file")
    else:
        print("No changes detected, skipping commit")
except GitHubAPIError as e:
    if e.status_code == 404:
        # File doesn't exist, create it
        commit_file(repo, path, new_content, branch, "Create file")
    else:
        raise

セッションごとのブランチ

一意のブランチ名を使って競合を回避します。

import datetime

session_id = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
branch_name = f"devlog-{session_id}"

commit_file(
    repo="user/project",
    path="DEVLOG.md",
    content=devlog_content,
    branch=branch_name,
    message="Session progress",
    create_branch_from="main"
)

複数リポジトリのワークフロー

複数のリポジトリをまたいで作業します。

repos = ["user/frontend", "user/backend", "user/docs"]

for repo in repos:
    commit_file(
        repo=repo,
        path="VERSION",
        content="2.0.0\n",
        branch="release-2.0",
        message="Bump version to 2.0.0"
    )

制限事項

• 対象環境：Claude.ai のチャットのみ（Claude Code は対象外）
• OAuth なし：Personal Access Token を手動で使用する必要があります
• Git 操作なし：REST API のみを使用します（clone、pull、rebase などは利用できません）
• ファイルサイズ：GitHub API では、1 ファイルあたり約 100MB の制限があります
• レート制限：認証済みユーザーは 1 時間あたり 5000 リクエストです
• ネットワーク必須：すべての操作にインターネット接続が必要です

関連項目

• references/credential-setup.md - 認証情報の設定手順ガイド
• references/iterating-integration.md - DEVLOG の自動同期パターン
• references/troubleshooting.md - よくある問題と解決方法
• GitHub REST API ドキュメント - GitHub API の公式リファレンス

トークン効率

このスキルは読み込み時に約 800 トークンを使用しますが、ネイティブの git アクセスを利用できない claude.ai のチャット環境で、GitHub の重要な操作を実行できます。永続的な状態管理とセッションをまたいだワークフローを可能にします。