通过 REST 与 GraphQL 分配 Issue

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

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 协作。