cyrus-setup-github

重要：~/.cyrus/.env または ~/.cyrus/ 内のファイルに対して、Read、Edit、Write ツールを絶対に使用しないでください。環境ファイルを操作するには、Bash コマンド（grep、printf >> など）のみを使用してください。シークレットを会話のコンテキストに読み込んではなりません。

GitHub のセットアップ

Cyrus がブランチ、コミット、プルリクエストを作成できるよう、GitHub CLI と git を設定します。オプションで GitHub App を作成し、Cyrus が PR のコメントやレビューでの @メンションを受信して応答したり、リベースやマージを自動化したり、CI の失敗に基づいて自動修正したりできるようにします（近日公開）。

---

パート A：GitHub CLI と Git の設定（送信）

ステップ 1：既存の設定を確認する

gh がすでに認証済みか確認します。

gh auth status 2>&1

認証済みの場合は、git の設定を確認します。

git config --global user.name
git config --global user.email

gh の認証と git の設定の両方が完了している場合は、ユーザーに次のように伝えます。

GitHub はすでに設定されています。Webhook のセットアップに進みます。

パート B に進みます。

ステップ 2：GitHub CLI を認証する

gh が認証されていない場合：

gh auth login

対話型のブラウザーフローが開きます。ユーザーが完了するまで待ちます。

完了後、次のコマンドで確認します。

gh auth status

ステップ 3：Git のユーザー情報を設定する

git のユーザー名またはメールアドレスが設定されていない場合は、希望する値をユーザーに尋ねます。

Cyrus が作成するコミットに表示する名前は何にしますか？ （例：ユーザーの名前、または「Cyrus Bot」）

コミットに表示するメールアドレスは何にしますか？ （例：ユーザーのメールアドレス、または noreply アドレス）

次に、これらを設定します。

git config --global user.name "<name>"
git config --global user.email "<email>"

ステップ 4：確認する

gh auth status
git config --global user.name
git config --global user.email

---

パート B：GitHub App と Webhook（受信 — オプション）

ユーザーに尋ねます。

Cyrus が PR のコメントやレビューでの GitHub @メンションに応答するようにしますか？

• はい — @メンションを有効にする：GitHub App を作成します。Cyrus は Webhook を介して PR のコメントやレビューを受信し、@メンションされたときに応答し、「changes requested」のレビューに対応できるようになります。
• いいえ — PR のみ：Cyrus はブランチ、コミット、PR を作成しますが、コメントには応答しません。

いいえの場合 → 完了に進みます。

ステップ 5：既存の Webhook 設定を確認する

grep -c '^GITHUB_WEBHOOK_SECRET=.' ~/.cyrus/.env 2>/dev/null
grep -c '^GITHUB_APP_ID=.' ~/.cyrus/.env 2>/dev/null
grep -c '^GITHUB_APP_INSTALLATION_ID=.' ~/.cyrus/.env 2>/dev/null
test -f ~/.cyrus/github-app.pem && echo "PEM exists" || echo "PEM missing"

4 つすべての確認結果が合格（1、1、1、「PEM が存在する」）の場合は、完了に進みます。Webhook はすでに設定されています。

ステップ 6：入力値を収集する

Webhook のベース URL を読み取ります。

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

CYRUS_BASE_URL が設定されていない場合は停止し、先にエンドポイントのセットアップ手順を実行するようユーザーに伝えてください。

オーケストレーターの AGENT_NAME の値を使用します（/cyrus-setup のステップ 0 で設定）。値がない場合は、次のように尋ねます。

GitHub App の名前は何にしますか？（例：「Cyrus」、「My Code Agent」）

重要 — GitHub の @メンション候補表示に関する注意点： GitHub の PR コメントでの候補表示では、App ボットではなく、実在する GitHub ユーザーアカウントのみが候補になります。そのため、同じ名前の GitHub ユーザーが存在しない限り、@your-bot は候補のドロップダウンに表示されません。手動で入力すればメンションは機能しますが、快適に利用するには、次のようにします。

名前を選ぶ前に、https://github.com/<name> で同じ名前が GitHub のユーザー名として利用可能か確認してください。利用可能であれば：

1. その名前で無料の GitHub ユーザーアカウントを作成する
2. そのアカウントを組織やリポジトリにコラボレーターとして招待する
3. GITHUB_BOT_USERNAME にそのユーザー名を設定する（ユーザーが @メンションで入力する名前であり、<slug>[bot] ではありません）

これが候補表示を有効にする最も簡単な方法です。GitHub の少々困った制限ですが、既知の回避策です。

一致する GitHub ユーザーがいなくても、手動で入力すれば @メンションは機能しますが、候補には表示されません。その場合、ボットの名前をリポジトリのコントリビューターとして表示するには、共著者設定（Git のメッセージテンプレート、または Co-authored-by: を追加する prepare-commit-msg フックを使用）を行う必要があります。こちらは手順が少し複雑です。

次のように尋ねます。

GitHub App はどこに作成しますか？

• 個人アカウント（github.com/settings/apps）
• 組織 — どの組織ですか？（github.com/organizations/<ORG>/settings/apps）

該当する場合は、組織名を保存します。

次のように尋ねます。

GitHub App のホームページ URL は何にしますか？ App の設定ページにウェブサイトとして表示されます。機能には影響せず、GitHub がリンクとして表示するだけです。多くの場合、会社のウェブサイト、GitHub の組織ページ、または任意のプレースホルダー URL を使用します。

（例：https://github.com/your-org、会社の URL、または https://example.com）

ステップ 7：マニフェスト JSON を作成する

AGENT_NAME、HOMEPAGE_URL、CYRUS_BASE_URL を置き換えてマニフェストを作成します。

{
  "name": "<AGENT_NAME>",
  "url": "<HOMEPAGE_URL>",
  "redirect_url": "http://localhost:8976",
  "hook_attributes": {
    "url": "<CYRUS_BASE_URL>/github-webhook",
    "active": true
  },
  "public": false,
  "default_permissions": {
    "contents": "write",
    "issues": "write",
    "pull_requests": "write",
    "repository_hooks": "write"
  },
  "default_events": [
    "issue_comment",
    "pull_request_review",
    "pull_request_review_comment",
    "repository"
  ]
}

注： GitHub のマニフェストフローでは redirect_url が必須です。実際のリダイレクト先には、この URL に ?code= パラメーターが追加されます。重要なのはコードであり、遷移先のページではありません。

ステップ 8：マニフェストを使って GitHub App を作成する

GitHub のマニフェストフローでは、manifest フィールドを含むフォームをアプリ作成 URL に POST します。ユーザーが承認すると、GitHub は code パラメーターを含む URL にリダイレクトします。

作成 URL を確認します。

• 個人用：https://github.com/settings/apps/new
• 組織用：https://github.com/organizations/<ORG>/settings/apps/new

GitHub のマニフェストフローでは、作成 URL に manifest フィールドを含むフォーム POSTが必要です。ページ自体にはマニフェスト入力欄はありません。どのパスでも同じヘルパー HTML ページの方式を使います。

まず、ヘルパーページを作成し、ローカル Web サーバー経由で公開します。この方法は、ローカル環境とリモート／ヘッドレス環境（サーバーに tmux／SSH で接続する場合など）の両方で使えます。マニフェスト JSON は HTML 属性内に配置するため、HTML エンティティにエスケープする必要があります（" を " に置き換えます）。

# Escape the manifest JSON for safe embedding in an HTML attribute
MANIFEST_HTML_ESCAPED=$(echo '<MANIFEST_JSON>' | sed 's/"/\&quot;/g')

cat > /tmp/github-app-manifest.html << HTMLEOF
<form method="post" action="<CREATION_URL>">
  <input type="hidden" name="manifest" value="$MANIFEST_HTML_ESCAPED">
  <p>Click the button to create the GitHub App:</p>
  <button type="submit" style="font-size:18px;padding:12px 24px;">Create GitHub App</button>
</form>
HTMLEOF

# Serve the page on a local port (works for headless/remote setups)
python3 -m http.server 8976 --directory /tmp &
HTTP_SERVER_PID=$!
echo "Serving at http://localhost:8976/github-app-manifest.html"

ユーザーがフローを完了したら、サーバーを停止します。

kill $HTTP_SERVER_PID 2>/dev/null

利用可能なものに応じて、自動化のパスを選択します。

1. claude-in-chrome MCP ツールが利用可能な場合 → パス A-1を使用します
2. agent-browser がインストールされ、Chrome のデバッグセッションに接続されている場合 → パス A-2を使用します
3. それ以外の場合 → パス B（手動）を使用します

パス A-1（claude-in-chrome）：

1. http://localhost:8976/github-app-manifest.html に移動します
2. 送信ボタンをクリックして、マニフェストを GitHub に POST します
3. GitHub の確認ページが表示されたら、Create GitHub App をクリックします
4. リダイレクト後、URL から code パラメーターを取り出します

パス A-2（agent-browser）：

agent-browser を使って同じ手順を行います。ヘルパーページに移動し、送信ボタンをクリックしてから、Create をクリックします。

パス B（手動）：

ユーザーに次のように伝えます。

1. ブラウザーで http://localhost:8976/github-app-manifest.html を開き、ボタンをクリックします
2. GitHub で権限を確認し、Create GitHub App をクリックします
3. リダイレクト後、ブラウザーのアドレスバーにあるURL 全体をコピーして、ここに貼り付けます

リダイレクト URL から code パラメーターを取り出します。

ステップ 9：コードを認証情報と交換する

重要： /app-manifests/<CODE>/conversions エンドポイントは一度しか使えません。必ず一度だけ呼び出してください。

# Store the full response temporarily (one-time-use endpoint — do NOT call twice)
gh api /app-manifests/<CODE>/conversions --method POST > /tmp/github-app-response.json

# Extract values (these are all secrets — handle via Bash only)
GITHUB_APP_ID=$(cat /tmp/github-app-response.json | jq -r '.id')
GITHUB_APP_SLUG=$(cat /tmp/github-app-response.json | jq -r '.slug')
GITHUB_WEBHOOK_SECRET=$(cat /tmp/github-app-response.json | jq -r '.webhook_secret')
GITHUB_APP_PEM=$(cat /tmp/github-app-response.json | jq -r '.pem')

# Clean up
rm /tmp/github-app-response.json

ステップ 10：認証情報を環境変数ファイルに書き込む

# Ensure directory exists (may not if running standalone outside cyrus-setup)
mkdir -p ~/.cyrus

# Webhook secret (for signature verification)
printf 'GITHUB_WEBHOOK_SECRET=%s\n' "$GITHUB_WEBHOOK_SECRET" >> ~/.cyrus/.env

# App ID (for token minting)
printf 'GITHUB_APP_ID=%s\n' "$GITHUB_APP_ID" >> ~/.cyrus/.env

# Bot username (for mention filtering — see note below about GitHub autocomplete)
printf 'GITHUB_BOT_USERNAME=%s\n' "$GITHUB_APP_SLUG" >> ~/.cyrus/.env

# Private key (multi-line — stored as a separate file)
printf '%s\n' "$GITHUB_APP_PEM" > ~/.cyrus/github-app.pem
chmod 600 ~/.cyrus/github-app.pem

# Ensure self-hosted mode is active (required for signature verification)
grep -q '^CYRUS_HOST_EXTERNAL=' ~/.cyrus/.env || printf 'CYRUS_HOST_EXTERNAL=true\n' >> ~/.cyrus/.env

すべての値が書き込まれたことを確認します。

grep -c '^GITHUB_WEBHOOK_SECRET=.' ~/.cyrus/.env
grep -c '^GITHUB_APP_ID=.' ~/.cyrus/.env
grep -c '^GITHUB_BOT_USERNAME=.' ~/.cyrus/.env
test -f ~/.cyrus/github-app.pem && echo "PEM exists" || echo "PEM missing"

すべてのチェックに合格する必要があります（1、1、1、「PEM exists」を返します）。

ステップ 11：リポジトリに App をインストールする

Cyrus が監視するリポジトリに GitHub App をインストールする必要があります。

次の URL に移動します：https://github.com/apps/<GITHUB_APP_SLUG>/installations/new

対象のリポジトリ（または「All repositories」）を選択し、Install をクリックします。

または、ブラウザーの自動化で URL に移動し、リポジトリを選択して Install をクリックします。

インストール後、インストール ID を取得します。

# Re-read GITHUB_APP_ID from .env (shell vars don't persist between blocks)
GITHUB_APP_ID=$(grep '^GITHUB_APP_ID=' ~/.cyrus/.env | cut -d= -f2-)

# Generate a JWT to authenticate as the app
GITHUB_APP_JWT=$(node -e "
const crypto = require('crypto');
const fs = require('fs');
const key = fs.readFileSync(process.env.HOME + '/.cyrus/github-app.pem', 'utf8');
const now = Math.floor(Date.now()/1000);
const header = Buffer.from(JSON.stringify({alg:'RS256',typ:'JWT'})).toString('base64url');
const payload = Buffer.from(JSON.stringify({iat:now-60,exp:now+600,iss:'$GITHUB_APP_ID'})).toString('base64url');
const sig = crypto.createSign('RSA-SHA256').update(header+'.'+payload).sign(key,'base64url');
console.log(header+'.'+payload+'.'+sig);
")

# List installations — if multiple, show all and let user pick
INSTALLATIONS=$(curl -s -H "Authorization: Bearer $GITHUB_APP_JWT" -H "Accept: application/vnd.github+json" https://api.github.com/app/installations)
echo "$INSTALLATIONS" | jq '.[] | {id, account: .account.login}'

インストールが複数ある場合は、どれを使うかユーザーに確認します。その後、インストール ID を書き込みます。

printf 'GITHUB_APP_INSTALLATION_ID=%s\n' "<INSTALLATION_ID>" >> ~/.cyrus/.env

確認します。

grep -c '^GITHUB_APP_INSTALLATION_ID=.' ~/.cyrus/.env

1 を返す必要があります。

完了

✓ GitHub CLI の認証が完了しました ✓ Git の ID を設定しました：<name> <email>

Webhook が有効になっている場合：

✓ GitHub App を作成しました：<GITHUB_APP_SLUG> ✓ Webhook シークレットと App の認証情報を ~/.cyrus/.env に保存しました ✓ 秘密鍵を ~/.cyrus/github-app.pem に保存しました ✓ App をインストールしました（インストール ID：<GITHUB_APP_INSTALLATION_ID>） ✓ Cyrus は PR コメント内の @<GITHUB_BOT_USERNAME> メンションに応答します

注： Webhook URL が正常に応答するのは、Cyrus の実行開始後です。セットアップ中に GitHub で Webhook 配信の失敗が表示された場合、Cyrus の起動後に自動で再試行されます。