> ## 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 一致：Session 归档后挂载关系一并失效，Session 期内若需要替换仓库或修改克隆路径，必须创建新的 Session。

## 核心流程

<Steps>
  <Step title="准备 GitHub 令牌">
    生成 GitHub Personal Access Token（推荐使用 fine-grained PAT），授予仓库读取/写入、Pull Request 等所需权限。该 token 是 GitHub 仓库资源的必填字段。
  </Step>

  <Step title="创建 Session 时挂载仓库">
    在创建 Session 的 `resources` 数组中加入 `type: "github_repository"`，把仓库 URL 与 PAT 一并传入。
  </Step>

  <Step title="Agent 在容器内访问代码">
    Agent 启动后即可在挂载路径下读取代码，使用 `Bash`/`Read`/`Write`/`Edit` 等工具修改文件。
  </Step>

  <Step title="（可选）创建 Pull Request">
    Agent 在仓库目录中使用 `git push` 推送分支，再调用 `gh` CLI 创建 Pull Request。
  </Step>
</Steps>

<Note>
  仓库资源的克隆与平台容器临时存储共享同一份磁盘空间。容器临时存储 24 小时未活跃后可能被回收，回收后再次唤醒 Session 时平台会重新初始化容器并按需重新克隆，磁盘上未提交的中间产物会丢失。详见 [容器参考 - 文件持久化](/zh/cloud-agents/container-reference#文件持久化)。
</Note>

## 仓库资源字段

GitHub 仓库资源使用以下字段；推荐在创建 Session 时一次性传入：

| 字段                    | 类型     | 必填 | 说明                                                |
| --------------------- | ------ | -- | ------------------------------------------------- |
| `type`                | string | 是  | 固定为 `"github_repository"`                         |
| `url`                 | string | 是  | 仓库 URL，例如 `https://github.com/your-org/your-repo` |
| `mount_path`          | string | 否  | 克隆到容器中的路径。省略时按仓库名自动推断                             |
| `authorization_token` | string | 是  | GitHub Personal Access Token，用于克隆与推送仓库            |

<Note>
  `authorization_token` 仅在创建请求或 token 轮转请求中传入；读取 Session 详情或 Session resources 时不会返回该字段。建议每个 Session 使用最小权限的 PAT，并在用完后吊销。
</Note>

## 创建 Session 时挂载 GitHub 仓库

调用 [创建 Session](/zh/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": "为 your-repo 修复 bug",
    "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` 字段包含归一化后的挂载描述。响应中不会返回 token：

```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": "你是代码审查专家。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
      }
    ],
    "skills": [],
    "version": 2
  },
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "为 your-repo 修复 bug",
  "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"
}
```

<Tip>
  Agent 命令默认 cwd 为 `/app`。把 `mount_path` 设为 `/app/<repo-name>` 后，Agent 在 system prompt 或用户消息里只需引用相对路径 `your-repo/...`，无需切目录。
</Tip>

## 挂载多个仓库

一次请求即可挂载多个仓库到不同 `mount_path`，例如同时挂载前端和后端代码：

```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": "全栈联调",
    "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 .
```

也可以与文件、Memory Store、Vault 等其他资源混用，详见 [Sessions — 创建时挂载资源](/zh/cloud-agents/sessions#创建时挂载资源)。

## 令牌权限模型

GitHub 提供两种 PAT：fine-grained PAT（推荐）和 classic PAT。在 Qoder Cloud Agents 中使用时，按"最小权限原则"申请仅与本次任务相关的权限。

### 推荐权限对照

下表给出常见 Agent 操作对应的 fine-grained PAT 权限。classic PAT 对应的是仓库范围的 `repo` scope。

| Agent 操作             | fine-grained PAT 权限（Repository permissions） |
| -------------------- | ------------------------------------------- |
| 克隆/读取私有仓库            | `Contents: Read`                            |
| 创建分支并推送              | `Contents: Read & Write`                    |
| 创建 / 评论 Pull Request | `Pull requests: Read & Write`               |
| 读取 Issues            | `Issues: Read`                              |
| 创建 / 评论 Issues       | `Issues: Read & Write`                      |
| 读取仓库元信息（必备）          | `Metadata: Read`                            |

<Tip>
  fine-grained PAT 可绑定到具体仓库（甚至特定的 organization 资源），相比 classic PAT 风险更低。建议为每个 Agent 任务申请独立的、短期有效的 PAT。
</Tip>

### 安全建议

1. 不要将 Session 创建请求体或包含 `resources` 的响应写入日志、截图或版本库，其中包含明文 PAT。
2. 任务完成后及时在 GitHub 设置中吊销 PAT；fine-grained PAT 也支持设置较短的 `Expiration`。
3. 即使是公开仓库也需要传入 PAT；建议为公开仓库使用只读、短期有效的 token，将权限暴露面降到最低。
4. 不同环境（开发 / 生产）使用不同的 PAT，便于审计。

## 创建 Pull Request 工作流

Agent 在挂载好的仓库目录中可以直接执行 `git` 与 `gh` 命令。运行镜像已内置 `git` 与 `gh` CLI，平台也会用仓库资源的 `authorization_token` 自动为容器配置 `GH_TOKEN`，无需手动安装或导出环境变量。要让 Agent 完成"修改 -> push -> 创建 PR"全流程，只需：

1. Agent 配置中启用 `agent_toolset_20260401` 工具集，至少包含 `Bash`、`Read`、`Write`、`Edit`，详见 [工具](/zh/cloud-agents/tools)。
2. 在 user message 中清晰描述任务、仓库路径与目标分支。

下面是一个端到端示例，假设 Session ID 为 `sess_019e5ce0bf9074b69c3481e93771a522`、仓库挂载在 `/app/your-repo`：

```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": "请在 /app/your-repo 中修复 issue #128（用户登录后无法刷新 token）。完整流程：\n1) cd /app/your-repo；\n2) git checkout -b fix/refresh-token；\n3) 修复 src/auth/refresh.ts 中的 bug 并补充单测；\n4) git add 改动并 git commit -m \"fix(auth): rotate refresh token on login\"；\n5) git push -u origin fix/refresh-token；\n6) 用 gh pr create --base main --head fix/refresh-token --title \"fix(auth): rotate refresh token on login\" --body \"Fixes #128\" 创建 Pull Request。"
          }
        ]
      }
    ]
  }'
```

<Note>
  平台会用仓库资源的 `authorization_token` 自动为容器配置 `GH_TOKEN`，`gh pr create` 在容器内可直接调用。如果该 PAT 没有 `Pull requests: Read & Write` 权限，PR 创建会失败；申请 PAT 时请按上文 [推荐权限对照](#推荐权限对照) 一并授予。
</Note>

## 配合 Agent 配置的最佳实践

* 在 Agent 的 `tools` 中启用 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`，覆盖代码搜索与修改场景。
* 在 Agent 的 `system` 提示中明确仓库挂载路径，例如："你的工作目录是 `/app/your-repo`，所有 git 与 `gh` 操作都应在该目录下执行。"
* 对长任务可以在 system prompt 中要求 Agent 在每轮结束时执行 `git status` 自检，避免漏 commit。
* 如需跨 Session 复用产物，让 Agent 在每轮结束前用 [Files API](/zh/cloud-agents/files) 上传关键产物（patch 文件、报告）；否则容器磁盘 24 小时回收后，未上传的中间文件会丢失。

## 常见问题

**Q: 仓库太大，克隆很慢怎么办？**

A: 当前资源挂载使用完整 clone，资源字段里没有浅克隆开关。对于体积非常大的 monorepo，建议拆分任务范围，或使用 [Files API](/zh/cloud-agents/files) 上传关键子目录/文件作为补充上下文。

**Q: PAT 过期或被吊销了怎么办？**

A: 后续 git/`gh` 操作会返回 401。需要创建新的 Session 并使用新 PAT；对于已挂载但尚未推送的修改，可以让 Agent 在 Session 内先 `git diff` 输出 patch，再用 [Files API](/zh/cloud-agents/files) 上传备份。

**Q: 是否支持 fork 私有仓库或访问 organization 内部仓库？**

A: 支持，只要 PAT 对目标仓库具备 `Contents: Read` 权限即可。组织开启了 SSO 时，PAT 必须先经过 SSO 授权（Authorize 按钮）才能用于克隆。

**Q: 是否支持 git submodule？**

A: 仓库资源不会额外声明 submodule 字段。需要使用 submodule 时，让 Agent 在仓库目录中执行 `git submodule update --init --recursive`，并确保 PAT 对所有 submodule 仓库都有读权限。

**Q: Session 运行中能换仓库吗？**

A: 不能。一旦 Session 创建完成且某个仓库已挂载，挂载关系不会因为 update 调用而被替换。如需切换仓库，请创建新的 Session。

**Q: Agent 修改的代码会自动推回 GitHub 吗？**

A: 不会。除非 Agent 在任务中显式执行 `git push`，所有修改只存在于容器临时存储。请在 user message 中明确要求"push 分支"或"创建 PR"。

**Q: GitHub Enterprise Server (GHES) 是否支持？**

A: GitHub 仓库资源只暴露 `url`、`mount_path` 和 `authorization_token` 字段，没有单独的 GHES 配置字段。使用 GitHub Enterprise Server 时，请确认 GHES 端点对外可达，并确认对应 token 可被 `gh`/git 用于该主机。

## 下一步

* [Sessions — 创建时挂载资源](/zh/cloud-agents/sessions#创建时挂载资源) — 资源挂载的整体说明
* [API — 创建 Session](/zh/cloud-agents/api/sessions/create) — 创建 Session 接口的完整请求体
* [Skills](/zh/cloud-agents/skills) — 复用代码审查、PR 创建等通用流程
* [容器参考](/zh/cloud-agents/container-reference) — 容器目录结构与磁盘行为