← ドキュメント一覧/ガイド

GitHub Token セットアップガイド

GitHub Token セットアップガイド

概要

Miyabi で必要な GitHub Personal Access Token (PAT) の作成と設定方法を説明します。適切なスコープの選択、セキュリティのベストプラクティス、トラブルシューティングについて学びます。

対象読者

  • Miyabi の新規ユーザー
  • GitHub API を使用する開発者
  • セキュリティ担当者
  • プロジェクト管理者

所要時間

  • 読了時間: 10 分
  • セットアップ時間: 5-10 分

前提知識

  • GitHub アカウントの基本操作
  • 環境変数の概念
  • コマンドラインの基礎

必要なスコープ

必須スコープ

Miyabi が正常に動作するために必要な権限です。

required_scopes:
  repo:
    description: "リポジトリへのフルアクセス"
    includes:
      - Issue の読み書き
      - PR の読み書き
      - コードの読み書き
      - Webhook の管理

  workflow:
    description: "GitHub Actions ワークフローの管理"
    includes:
      - Workflow ファイルの更新
      - Workflow の実行トリガー

  read:project:
    description: "GitHub Projects V2 の読み取り"
    includes:
      - プロジェクトボードの情報取得
      - アイテムのステータス確認

  write:project:
    description: "GitHub Projects V2 への書き込み"
    includes:
      - Issue/PR をプロジェクトに追加
      - アイテムのステータス更新
      - カスタムフィールドの更新

推奨スコープ

Organization で使用する場合の追加スコープです。

recommended_scopes:
  read:org:
    description: "Organization 情報の読み取り"
    use_case: "Organization プロジェクト使用時"

  notifications:
    description: "通知へのアクセス"
    use_case: "通知の自動管理"

セットアップ手順

ステップ 1: Token の作成

Classic Token の作成

# 1. GitHub にアクセス
open https://github.com/settings/tokens

# 2. "Generate new token" をクリック
# 3. "Generate new token (classic)" を選択
# 4. Token に名前を付ける
#    例: "Miyabi - MacBook Pro"

# 5. 有効期限を選択
#    推奨: 90 days 以上

# 6. スコープを選択
#    ✅ repo (全て)
#    ✅ workflow
#    ✅ read:project
#    ✅ write:project
#    ✅ notifications (推奨)
#    ✅ read:org (Organization 使用時)

# 7. "Generate token" をクリック

# 8. Token をコピー
#    ⚠️ このページを離れると再表示できません

Fine-grained Token の作成（推奨）

# 1. GitHub にアクセス
open https://github.com/settings/tokens?type=beta

# 2. "Generate new token" をクリック

# 3. Token の詳細を設定
#    - Token name: "Miyabi - Production"
#    - Expiration: 90 days
#    - Description: "Miyabi automation token"

# 4. Repository access を選択
#    - All repositories (すべて)
#    - または Only select repositories (特定のリポジトリ)

# 5. Permissions を設定

## Repository permissions:
# Contents: Read and write
# Issues: Read and write
# Pull requests: Read and write
# Workflows: Read and write
# Metadata: Read-only (自動)

## Organization permissions (Organization の場合):
# Projects: Read and write
# Members: Read-only

# 6. "Generate token" をクリック

# 7. Token をコピーして安全に保存

ステップ 2: 環境変数の設定

オプション A: .env ファイル（推奨）

# プロジェクトルートに .env ファイルを作成
cat > .env << 'EOF'
GITHUB_TOKEN=ghp_your_token_here
ANTHROPIC_API_KEY=sk-ant-your_key_here
DEVICE_IDENTIFIER=MacBook Pro 16-inch
EOF

# .env が .gitignore に含まれていることを確認
grep .env .gitignore || echo ".env" >> .gitignore

# 権限を制限（重要）
chmod 600 .env

オプション B: 環境変数を直接設定

macOS / Linux:

# 一時的な設定（現在のセッションのみ）
export GITHUB_TOKEN=ghp_your_token_here

# 永続的な設定
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc

# zsh の場合
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

# 一時的な設定
$env:GITHUB_TOKEN="ghp_your_token_here"

# 永続的な設定（ユーザー環境変数）
[System.Environment]::SetEnvironmentVariable(
  "GITHUB_TOKEN",
  "ghp_your_token_here",
  "User"
)

オプション C: GitHub CLI との連携

# GitHub CLI で認証
gh auth login

# Token を環境変数に設定
export GITHUB_TOKEN=$(gh auth token)

# または .env ファイルに追加
echo "GITHUB_TOKEN=$(gh auth token)" >> .env

ステップ 3: Token の検証

# GitHub CLI で状態確認
gh auth status

# 出力例:
# github.com
#   ✓ Logged in to github.com as yourusername (keyring)
#   ✓ Git operations protocol: https
#   ✓ Token: ghp_************************************
#   ✓ Token scopes: repo, workflow, read:project, write:project

# 環境変数を確認
echo $GITHUB_TOKEN

# Miyabi で動作確認
npm run project:info

# 成功すれば:
# ✅ GitHub Token: 有効
# ✅ Projects V2 アクセス: OK
# ✅ 必要なスコープ: すべて存在

セキュリティのベストプラクティス

すべきこと

security_best_practices:
  storage:
    - Token は .env ファイルに保存
    - .env を .gitignore に追加
    - ファイル権限を 600 に設定

  rotation:
    - Token は定期的に再生成（90日ごと推奨）
    - 古い Token は削除

  scope:
    - 必要最小限のスコープのみ付与
    - 使用しないスコープは削除

  organization:
    - Organization の場合は SSO を有効化
    - Fine-grained Token を使用
    - Repository アクセスを限定

  monitoring:
    - Token の使用状況を監視
    - 不正アクセスの兆候をチェック

してはいけないこと

security_anti_patterns:
  ❌ Token をコードに直接記述
  ❌ Token を公開リポジトリにコミット
  ❌ Token をチームメンバーと共有
  ❌ 不要なスコープを付与
  ❌ Token を平文でメッセージに含める
  ❌ Token に有効期限を設定しない
  ❌ .env ファイルを Git に追加

トラブルシューティング

エラー 1: Scope が不足

症状:

Error: Your token has not been granted the required scopes
Missing scopes: read:project, write:project

解決方法:

# 1. Token の設定ページにアクセス
open https://github.com/settings/tokens

# 2. 該当する Token を選択

# 3. 不足しているスコープを追加
#    ✅ read:project
#    ✅ write:project

# 4. "Update token" をクリック

# 5. 必要に応じて Token を再生成

# 6. .env ファイルまたは環境変数を更新

エラー 2: Token が設定されていない

症状:

Error: GITHUB_TOKEN not set
Please set GITHUB_TOKEN environment variable

解決方法:

# .env ファイルが存在するか確認
ls -la .env

# 存在しない場合は作成
echo "GITHUB_TOKEN=ghp_your_token_here" > .env

# 環境変数を source
set -a && source .env && set +a

# または直接設定
export GITHUB_TOKEN=ghp_your_token_here

# 確認
echo $GITHUB_TOKEN

エラー 3: Token の有効期限切れ

症状:

Error: Bad credentials
401 Unauthorized

解決方法:

# GitHub で Token の状態を確認
gh auth status

# Token が期限切れの場合は再認証
gh auth refresh

# または新しい Token を作成
open https://github.com/settings/tokens

# 新しい Token を .env に設定

エラー 4: gh CLI と環境変数が異なる

説明: gh CLI は独自の認証を管理しており、GITHUB_TOKEN 環境変数とは別です。

解決方法:

# 両方を設定する

# 1. gh CLI の認証
gh auth login

# 2. 環境変数を gh CLI の Token と同期
export GITHUB_TOKEN=$(gh auth token)

# または .env ファイルに追加
echo "GITHUB_TOKEN=$(gh auth token)" >> .env

# 確認
gh auth status
echo $GITHUB_TOKEN

エラー 5: SSO 認証が必要

症状:

Error: Resource protected by organization SAML enforcement

解決方法:

# 1. Token の設定ページにアクセス
open https://github.com/settings/tokens

# 2. Token を選択

# 3. SSO Organization の横にある "Configure SSO" をクリック

# 4. "Authorize" をクリック

# 5. Organization の SSO ログインを完了

Token の管理

複数環境での管理

# 開発環境
cat > .env.development << EOF
GITHUB_TOKEN=ghp_dev_token_here
DEVICE_IDENTIFIER=MacBook Pro - Dev
EOF

# 本番環境
cat > .env.production << EOF
GITHUB_TOKEN=ghp_prod_token_here
DEVICE_IDENTIFIER=Production Server
EOF

# 環境に応じて読み込む
if [ "$NODE_ENV" = "production" ]; then
  source .env.production
else
  source .env.development
fi

Token の監査

# Token の使用状況を確認
gh api user

# Token のスコープを確認
gh api user -i | grep x-oauth-scopes

# Token の詳細情報
gh api /applications/grants

# Token を使った最近のアクティビティ
gh api /user/events

Token のローテーション

# 1. 新しい Token を作成
NEW_TOKEN=ghp_new_token_here

# 2. .env を更新（バックアップを取る）
cp .env .env.backup
sed -i.bak "s/GITHUB_TOKEN=.*/GITHUB_TOKEN=$NEW_TOKEN/" .env

# 3. 動作確認
npm run project:info

# 4. 成功したら古い Token を削除
# https://github.com/settings/tokens で削除

# 5. バックアップを削除
rm .env.backup .env.bak

関連機能

Miyabi で Token を使用する機能

features_requiring_token:
  project_management:
    - npm run project:info      # プロジェクト情報取得
    - npm run project:add        # Issue/PR 追加
    - npm run project:report     # レポート生成

  parallel_agents:
    - npm run agents:parallel:issues  # Issue 並列処理
    - npm run agents:parallel:todos   # TODO 並列処理

  kpi_collection:
    - npm run kpi:collect            # KPI データ収集
    - npm run dashboard:generate     # ダッシュボード生成

  github_operations:
    - gh issue create                # Issue 作成
    - gh pr create                   # PR 作成
    - gh workflow run                # Workflow 実行

参考リンク

関連ドキュメント

次のステップ

  1. Anthropic API Key を設定する
  2. プロジェクト初期化 を実行する
  3. 最初の Agent を動かしてみる

最終更新: 2025-10-10 バージョン: 2.0.0 ソース: GITHUB_TOKEN_SETUP.md メンテナー: Miyabi Security Team

← ドキュメント一覧ホームへ →