通过 REST 与 GraphQL 分配 Issue

查询 Copilot 身份，创建或分配 Issue，并指定目标仓库、分支和角色。

This page has not been translated into English yet. The original Chinese version is shown below.

Issues API 可以把新建或已有 Issue 分配给 Copilot，并附加目标仓库、分支、指令、custom agent 和模型。该能力当前为 public preview。

认证与权限

使用用户身份 token，例如 PAT 或 GitHub App user-to-server token。官方为 Issue 分配列出的 fine-grained PAT 权限为 metadata 读取，以及 Actions、Contents、Issues、Pull requests 的读写；classic PAT 使用 repo scope。

这些是本页 Issue 分配流程的要求，不是Agent tasks API的 Agent tasks 权限表。Token 有权限还需要 cloud agent 对用户和仓库可用。

参数映射

GraphQL agentAssignment	REST agent_assignment	含义
targetRepositoryId	target_repo	工作仓库；GraphQL 用全局 ID，REST 用 OWNER/REPO
baseRef	base_branch	起点分支
customInstructions	custom_instructions	补充任务指令
customAgent	custom_agent	自定义角色
model	model	模型

这些字段是可选的任务定制输入。不要把 tasks API 的 base_ref 原样放进 Issue 的 agent_assignment。

REST：给已有 Issue 添加 Copilot

下面使用 Bash 或 zsh 的 here-string，把 JSON 送给 gh api --input -：

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \
  --input - <<< '{
    "assignees": ["copilot-swe-agent[bot]"],
    "agent_assignment": {
      "target_repo": "OWNER/REPO",
      "base_branch": "main",
      "custom_instructions": "Fix the reported bug and validate the change."
    }
  }'

替换仓库、Issue 编号和分支。这是官方 Issue 教程的 API 版本，不与新 agent-tasks 参考的版本头混写。

创建新 Issue 使用 POST /repos/OWNER/REPO/issues，请求增加 title、body、assignees 和可选 agent_assignment；修改已有 Issue 使用 PATCH /repos/OWNER/REPO/issues/ISSUE_NUMBER。若只想添加受理人，使用上面的专门 assignees 端点，避免把添加与替换操作混淆。

GraphQL：发现可用的 Copilot

GraphQL 请求必须包含：

GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection

查询目标仓库可分配的 actor：

query {
  repository(owner: "octo-org", name: "octo-repo") {
    id
    suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {
      nodes {
        login
        __typename
        ... on Bot { id }
        ... on User { id }
      }
    }
  }
}

查找 login 为 copilot-swe-agent 的记录并保存其全局 ID。REST 的受理人字符串带 [bot]，GraphQL 查询中的 login 不带；不要自行拼接一个全局 ID。

GraphQL：选择合适 mutation

Mutation	使用场景
createIssue	新建 Issue，并在 assigneeIds 中指定 bot ID
updateIssue	更新已有 Issue 及受理人
replaceActorsForAssignable	按 actorIds 替换受理人
addAssigneesToAssignable	添加受理人并保留其他已有受理人

已有 Issue 的全局 ID 可通过 repository { issue(number: ...) { id } } 查询。新建则使用仓库全局 ID。

下面展示为已有 Issue 添加 Copilot，同时传入补充指令：

gh api graphql -f query='mutation {
  addAssigneesToAssignable(input: {
    assignableId: "ISSUE_ID",
    assigneeIds: ["BOT_ID"],
    agentAssignment: {
      targetRepositoryId: "REPOSITORY_ID",
      baseRef: "main",
      customInstructions: "Fix the reported bug and validate the change."
    }
  }) {
    assignable {
      ... on Issue {
        id
        title
        assignees(first: 10) { nodes { login } }
      }
    }
  }
}' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'

替换三个 ID 后再发送。分配成功后继续通过 PR 和会话日志跟踪；Issue 后续评论不会自动传给已启动任务，见Issue 协作。