跳转到主要内容
Qoder Cloud Agents 支持把 GitHub 仓库作为 Session 的资源挂载到容器中。Session 启动后，平台会自动 clone 仓库到指定路径，Agent 可以像在本地工作树中一样读取、修改、提交、推送代码，并配合 gh CLI 创建 Pull Request。 仓库资源的归属与 Session 一致：Session 归档后挂载关系一并失效，Session 期内若需要替换仓库或修改克隆路径，必须创建新的 Session。

​
核心流程

1

准备 GitHub 令牌

生成 GitHub Personal Access Token（推荐使用 fine-grained PAT），授予仓库读取/写入、Pull Request 等所需权限。该 token 是 GitHub 仓库资源的必填字段。
2

创建 Session 时挂载仓库

在创建 Session 的 resources 数组中加入 type: "github_repository"，把仓库 URL 与 PAT 一并传入。
3

Agent 在容器内访问代码

Agent 启动后即可在挂载路径下读取代码，使用 Bash/Read/Write/Edit 等工具修改文件。
4

（可选）创建 Pull Request

Agent 在仓库目录中使用 git push 推送分支，再调用 gh CLI 创建 Pull Request。
仓库资源的克隆与平台容器临时存储共享同一份磁盘空间。容器临时存储 24 小时未活跃后可能被回收，回收后再次唤醒 Session 时平台会重新初始化容器并按需重新克隆，磁盘上未提交的中间产物会丢失。详见 容器参考 - 文件持久化。

​
仓库资源字段

GitHub 仓库资源使用以下字段；推荐在创建 Session 时一次性传入：
字段类型必填说明
typestring是固定为 "github_repository"
urlstring是仓库 URL，例如 https://github.com/your-org/your-repo
mount_pathstring否克隆到容器中的路径。省略时按仓库名自动推断
authorization_tokenstring是GitHub Personal Access Token，用于克隆与推送仓库
authorization_token 仅在创建请求或 token 轮转请求中传入；读取 Session 详情或 Session resources 时不会返回该字段。建议每个 Session 使用最小权限的 PAT，并在用完后吊销。

​
创建 Session 时挂载 GitHub 仓库

调用 创建 Session 接口，在 resources[] 中传入仓库描述： 
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： 
{
  "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"
}
Agent 命令默认 cwd 为 /app。把 mount_path 设为 /app/<repo-name> 后，Agent 在 system prompt 或用户消息里只需引用相对路径 your-repo/...，无需切目录。

​
挂载多个仓库

一次请求即可挂载多个仓库到不同 mount_path，例如同时挂载前端和后端代码： 
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 — 创建时挂载资源。

​
令牌权限模型

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 RequestPull requests: Read & Write
读取 IssuesIssues: Read
创建 / 评论 IssuesIssues: Read & Write
读取仓库元信息（必备）Metadata: Read
fine-grained PAT 可绑定到具体仓库（甚至特定的 organization 资源），相比 classic PAT 风险更低。建议为每个 Agent 任务申请独立的、短期有效的 PAT。

​
安全建议

  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，详见 工具。
  2. 在 user message 中清晰描述任务、仓库路径与目标分支。
下面是一个端到端示例，假设 Session ID 为 sess_019e5ce0bf9074b69c3481e93771a522、仓库挂载在 /app/your-repo： 
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。"
          }
        ]
      }
    ]
  }'
平台会用仓库资源的 authorization_token 自动为容器配置 GH_TOKEN，gh pr create 在容器内可直接调用。如果该 PAT 没有 Pull requests: Read & Write 权限，PR 创建会失败；申请 PAT 时请按上文 推荐权限对照 一并授予。

​
配合 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 上传关键产物（patch 文件、报告）；否则容器磁盘 24 小时回收后，未上传的中间文件会丢失。

​
常见问题

Q: 仓库太大，克隆很慢怎么办？ A: 当前资源挂载使用完整 clone，资源字段里没有浅克隆开关。对于体积非常大的 monorepo，建议拆分任务范围，或使用 Files API 上传关键子目录/文件作为补充上下文。 Q: PAT 过期或被吊销了怎么办？ A: 后续 git/gh 操作会返回 401。需要创建新的 Session 并使用新 PAT；对于已挂载但尚未推送的修改，可以让 Agent 在 Session 内先 git diff 输出 patch，再用 Files API 上传备份。 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 用于该主机。

​
下一步