访问 GitHub

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

核心流程

准备 GitHub 令牌

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

创建 Session 时挂载仓库

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

Agent 在容器内访问代码

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

（可选）创建 Pull Request

Agent 在仓库目录中使用 git push 推送分支，再调用 gh CLI 创建 Pull Request。

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

仓库资源字段

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，用于克隆与推送仓库

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 权限（Repository permissions）
克隆/读取私有仓库	`Contents: Read`
创建分支并推送	`Contents: Read & Write`
创建 / 评论 Pull Request	`Pull requests: Read & Write`
读取 Issues	`Issues: Read`
创建 / 评论 Issues	`Issues: Read & Write`
读取仓库元信息（必备）	`Metadata: Read`

安全建议

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

创建 Pull Request 工作流

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

Agent 配置中启用 agent_toolset_20260401 工具集，至少包含 Bash、Read、Write、Edit，详见工具。
在 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 用于该主机。

下一步

Sessions — 创建时挂载资源 — 资源挂载的整体说明
API — 创建 Session — 创建 Session 接口的完整请求体
Skills — 复用代码审查、PR 创建等通用流程
容器参考 — 容器目录结构与磁盘行为

​核心流程

​仓库资源字段

​创建 Session 时挂载 GitHub 仓库

​挂载多个仓库

​令牌权限模型

​推荐权限对照

​安全建议

​创建 Pull Request 工作流

​配合 Agent 配置的最佳实践

​常见问题

​下一步

核心流程

仓库资源字段

创建 Session 时挂载 GitHub 仓库

挂载多个仓库

令牌权限模型

推荐权限对照

安全建议

创建 Pull Request 工作流

配合 Agent 配置的最佳实践

常见问题

下一步