> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub にアクセスする
> GitHub リポジトリを Session コンテナにマウントし、Agent がコードの読み取り・修正・Pull Request の作成を行えるようにします。
Qoder Cloud Agents では、GitHub リポジトリを Session のリソースとしてアタッチできます。Session が起動すると、プラットフォームは選択したパスにリポジトリをコンテナへ clone します。Agent はローカルのチェックアウトで作業するのと同じようにコードを読み取り・編集・コミット・プッシュでき、[`gh` CLI](https://cli.github.com/) を使って Pull Request を作成できます。
リポジトリリソースのライフサイクルは、所有する Session と共有されます。URL や `mount_path` を変更する必要がある場合は、新しい Session を作成してください。実行中の Session ではマウント済みリポジトリを差し替えられません。
## ワークフロー
タスクに必要なリポジトリスコープ（読み取り、書き込み、Pull Request 作成など）を付与した GitHub Personal Access Token（fine-grained PAT を推奨）を生成します。このトークンはすべての GitHub リポジトリリソースで必須のフィールドです。
create-Session リクエストの `resources` に `type: "github_repository"` のエントリを追加し、URL と PAT を含めます。
Session が起動すると、Agent はマウントパスでコードを読み取り、`Bash`、`Read`、`Write`、`Edit` などでファイルを変更できます。
Agent に `git push` でブランチをプッシュさせ、リポジトリディレクトリ内から `gh` CLI で PR を作成させます。
リポジトリの clone はコンテナの一時ディスク上に存在します。24 時間操作がないと、プラットフォームがディスクを回収する場合があります。Session は会話を再開できますが、ディスク上の未コミットの変更は失われます。[Container reference — File persistence](/ja/cloud-agents/container-reference#file-persistence) を参照してください。
## リポジトリリソースのフィールド
GitHub リポジトリリソースは以下のフィールドを使用します。Session 作成時に渡してください。
| フィールド | 型 | 必須 | 説明 |
| --------------------- | ------ | --- | ---------------------------------------------------- |
| `type` | string | はい | `"github_repository"` でなければなりません |
| `url` | string | はい | リポジトリ URL（例：`https://github.com/your-org/your-repo`） |
| `mount_path` | string | いいえ | コンテナ内で clone するパス。デフォルトはリポジトリ名から導出されるパス |
| `authorization_token` | string | はい | リポジトリの clone とプッシュに使用する GitHub Personal Access Token |
`authorization_token` は作成リクエストまたはトークンローテーションのリクエストでのみ渡します。Session 詳細や Session リソースを取得しても返されません。Session ごとに最小権限の PAT を使用し、終了したら失効させてください。
## Session 作成時に GitHub リポジトリをマウントする
[Create Session](/ja/cloud-agents/api/sessions/create) を呼び出し、`resources[]` 内にリポジトリを含めます。
```bash theme={null}
curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"agent": {"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "type": "agent", "version": 2},
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
"title": "Fix bug in your-repo",
"resources": [
{
"type": "github_repository",
"url": "https://github.com/your-org/your-repo",
"mount_path": "/app/your-repo",
"authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
]
}' | jq .
```
成功時のレスポンスは **HTTP 200 OK** で、`resources` 配列には正規化されたマウント記述が含まれます。トークンは返されません。
```json theme={null}
{
"id": "sess_019e5ce0bf9074b69c3481e93771a522",
"type": "session",
"agent": {
"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
"type": "agent",
"name": "code-reviewer",
"description": "",
"model": {"id": "ultimate", "effective_context_window": 200000},
"system": "You are a code review expert.",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
}
],
"skills": [],
"version": 2
},
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
"status": "idle",
"title": "Fix bug in your-repo",
"metadata": {},
"resources": [
{
"type": "github_repository",
"url": "https://github.com/your-org/your-repo",
"mount_path": "/app/your-repo",
"checkout": null,
"created_at": "2026-05-18T12:00:00Z",
"updated_at": "2026-05-18T12:00:00Z"
}
],
"vault_ids": [],
"deployment_id": null,
"outcome_evaluations": [],
"stats": {
"active_seconds": 0,
"duration_seconds": 0
},
"environment_variables": {},
"archived_at": null,
"created_at": "2026-05-18T12:00:00Z",
"updated_at": "2026-05-18T12:00:00Z"
}
```
Agent のコマンドは cwd `/app` で実行されます。`mount_path` を `/app/` に設定すると、Agent はディレクトリを変更せずに、system プロンプトやユーザーメッセージ内で `your-repo/...` のような相対パスを直接参照できます。
## 複数のリポジトリをマウントする
1 回のリクエストで、異なる `mount_path` の下に複数のリポジトリをアタッチできます。たとえばフロントエンドとバックエンドのコードを同じ Session に取り込む場合などです。
```bash theme={null}
curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"agent": {"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "type": "agent", "version": 2},
"environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
"title": "Full-stack debugging",
"resources": [
{
"type": "github_repository",
"url": "https://github.com/your-org/frontend",
"mount_path": "/app/frontend",
"authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
{
"type": "github_repository",
"url": "https://github.com/your-org/backend",
"mount_path": "/app/backend",
"authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
]
}' | jq .
```
リポジトリは files、Memory Stores、Vaults と混在させられます。[Sessions — 作成時にリソースをアタッチ](/ja/cloud-agents/sessions#attach-resources-at-creation) を参照してください。
## トークン権限モデル
GitHub には 2 種類の PAT があります。fine-grained PAT（推奨)と classic PAT です。どちらを選んでも、最小権限の原則に従い、タスクに必要なスコープのみを付与してください。
### 推奨される権限
以下の表は、一般的な Agent のアクションと fine-grained PAT のリポジトリ権限の対応を示しています。classic PAT の場合は `repo` スコープが相当します。
| Agent のアクション | fine-grained PAT の権限（Repository permissions） |
| ------------------------- | -------------------------------------------- |
| プライベートリポジトリの clone / 読み取り | `Contents: Read` |
| ブランチの作成とプッシュ | `Contents: Read & Write` |
| Pull Request の作成 / コメント | `Pull requests: Read & Write` |
| Issue の読み取り | `Issues: Read` |
| Issue の作成 / コメント | `Issues: Read & Write` |
| リポジトリメタデータの読み取り（常に必須） | `Metadata: Read` |
fine-grained PAT は特定のリポジトリ（さらには特定の組織リソース)にスコープを限定でき、classic PAT よりも安全です。Agent のタスクごとに、新しく短命な PAT を発行してください。
### セキュリティガイダンス
1. Session 作成リクエストのボディや `resources` を含むレスポンスは、ログ・スクリーンショット・バージョン管理に残さないでください。これらには平文の PAT が含まれます。
2. タスクが終了したら、GitHub の設定で速やかに PAT を失効させてください。fine-grained PAT は短い `Expiration` 値もサポートします。
3. パブリックリポジトリでも PAT は必須です。パブリックの場合は、露出面を最小化するために読み取り専用で短命なトークンを使うことを推奨します。
4. 環境ごと（開発と本番)に異なる PAT を使い、監査証跡が意味を保つようにしてください。
## Pull Request ワークフロー
マウント済みのリポジトリディレクトリ内で、Agent は `git` と `gh` コマンドを直接実行できます。ランタイムイメージには `git` と `gh` CLI の両方が同梱されており、プラットフォームはリポジトリリソースの `authorization_token` を自動的に `GH_TOKEN` としてコンテナに渡します。`gh` のインストールやトークンの手動エクスポートは不要です。「編集 -> プッシュ -> PR 作成」の一連のフローを実行するには:
1. Agent で `agent_toolset_20260401` ツールセットを有効化し、少なくとも `Bash`、`Read`、`Write`、`Edit` を含めます。[Agent ツール](/ja/cloud-agents/tools) を参照してください。
2. ユーザーメッセージでタスク、リポジトリパス、対象ブランチを明確に指定します。
以下の例は、`/app/your-repo` にリポジトリをマウントした Session ID `sess_019e5ce0bf9074b69c3481e93771a522` を前提としています。
```bash theme={null}
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Please fix issue #128 in /app/your-repo (users cannot refresh their token after login). Full flow:\n1) cd /app/your-repo;\n2) git checkout -b fix/refresh-token;\n3) fix the bug in src/auth/refresh.ts and add unit tests;\n4) git add the changes and git commit -m \"fix(auth): rotate refresh token on login\";\n5) git push -u origin fix/refresh-token;\n6) run gh pr create --base main --head fix/refresh-token --title \"fix(auth): rotate refresh token on login\" --body \"Fixes #128\" to open the Pull Request."
}
]
}
]
}'
```
プラットフォームはリポジトリリソースの `authorization_token` からコンテナ内の `GH_TOKEN` を自動構成するため、`gh pr create` はそのまま動作します。その PAT に `Pull requests: Read & Write` がないと PR 作成は失敗します。[推奨される権限](#recommended-permissions) に記載のスコープを事前に PAT へ付与しておいてください。
## Agent 構成のベストプラクティス
* コード検索と修正をカバーするため、Agent の `tools` で `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep` を有効化します。
* Agent の `system` プロンプトでマウントパスを明示します。例：「Your working directory is `/app/your-repo`. Run all `git` and `gh` commands inside this folder.」
* 長いタスクでは、未コミットの変更が残らないよう、各ターンの最後に `git status` を実行させます。
* Session をまたいで成果物を引き継ぐには、重要な出力（パッチ、レポート)を [Files API](/ja/cloud-agents/files) でアップロードさせてください。アップロードしていない中間ファイルは、24 時間操作がないとコンテナディスクの回収時に失われます。
## FAQ
**Q: リポジトリが巨大です。clone を高速化するには?**
A: リポジトリリソースは現在フル clone を使用しており、リソースオブジェクトに shallow-clone のスイッチはありません。非常に大きな monorepo の場合は、タスクのスコープを絞るか、関連するサブディレクトリ/ファイルを [Files API](/ja/cloud-agents/files) で補助的なコンテキストとしてアップロードしてください。
**Q: PAT が期限切れまたは失効した場合は?**
A: 以降の git / `gh` の呼び出しは 401 を返します。新しい PAT で新しい Session を作成してください。プッシュしていないローカルの変更がある場合は、まず Agent に `git diff` のパッチを出力させ、[Files API](/ja/cloud-agents/files) でアップロードして保全してください。
**Q: プライベートな fork や組織内部のリポジトリはサポートされますか?**
A: はい。PAT が対象リポジトリに `Contents: Read` を持っていれば可能です。組織が SSO を強制している場合は、clone する前に PAT を認可（Authorize ボタン)する必要があります。
**Q: git サブモジュールはサポートされますか?**
A: リポジトリリソースに専用のサブモジュールフィールドはありません。サブモジュールが必要な場合は、Agent にリポジトリ内で `git submodule update --init --recursive` を実行させ、PAT がすべてのサブモジュールリポジトリへの読み取りアクセスを持つことを確認してください。
**Q: 実行中の Session でリポジトリを差し替えられますか?**
A: いいえ。特定のリポジトリマウントで Session を作成すると、そのマウントは更新呼び出しで置き換えられません。別のリポジトリや `mount_path` が必要な場合は新しい Session を作成してください。
**Q: Agent は変更を自動的に GitHub にプッシュしますか?**
A: いいえ。Agent がターン内で `git push` を実行しない限り、編集はコンテナの一時ディスク上に残ります。ユーザーメッセージで「ブランチをプッシュする」「PR を作成する」と明示してください。
**Q: GitHub Enterprise Server (GHES) はサポートされますか?**
A: GitHub リポジトリリソースは `url`、`mount_path`、`authorization_token` のみを公開しており、専用の GHES 構成フィールドはありません。GitHub Enterprise Server の場合は、GHES エンドポイントがプラットフォームから到達可能であること、トークンがそのホストで `gh`/git と動作することを確認してください。
## 次のステップ
* [Sessions — 作成時にリソースをアタッチ](/ja/cloud-agents/sessions#attach-resources-at-creation) — リソースマウントの概要
* [API — Create a session](/ja/cloud-agents/api/sessions/create) — Session 作成の完全なリクエストボディ
* [Skills](/ja/cloud-agents/skills) — コードレビューや PR ワークフローを再利用する
* [Container reference](/ja/cloud-agents/container-reference) — ディレクトリ構成とディスクの挙動