用途:在读写 GitHub Projects (v2) 时提供接口选择与调用要点,涵盖 REST、GraphQL、字段 ID、条目生命周期、内建工作流和 Actions 自动化。\n\n主要能力:\n- API 选择:REST 走 /orgs/{org}/projectsV2/... 与 /users/{username}/projectsV2/...(API 版本 2026-03-10);列字段或条目、脚本简单读取、想要纯 JSON 时用 REST;要一次跨项目+条目+内容取回、或需 REST 未暴露的类型、以及变更条目字段值时用 GraphQL。REST 较新,并非与 GraphQL 一一对应,使用前需确认操作是否受支持。\n- 令牌:org 项目端点接受细粒度 PAT(需 Projects 组织权限)、App 用户令牌、安装令牌;用户拥有的项目端点三种细粒度令牌全部拒绝。若用户项目调用返回 403,是凭据类型问题而非权限级别。\n- 标识符:project number 用于 URL 与 REST 路径;node ID 用于 GraphQL,并在 REST 中作为 node_id 返回;字段/条目整数 id 仅用于 REST 路径。可用 REST 读、再拿 node_id 用 GraphQL 写。\n- 字段类型:text、number、date、single_select、iteration,以及内建 Title、Assignees、Status、Labels、Milestone、Repository、Linked pull requests、父/子议题进度字段。单选选项和迭代各有自己的 ID,不能按名称设置状态,必须先解析选项 ID。\n- 条目:内容为 DraftIssue、Issue 或 PullRequest 的联合类型,查询需用内联片段;草稿议题只存在于项目内,转为真实议题会改变内容类型但保留条目。多次字段更新可用别名合并到一个 mutation。\n- 分页:项目端点使用游标分页(Link 头的 before/after),不是 page;递增 page 号的代码会一直返回第一页。\n\n使用方式:可先做字段查询解析选项 ID,再执行更新;REST 列字段示例:curl -L -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $TOKEN" -H "X-GitHub-Api-Version: 2026-03-10" https://api.github.com/orgs/ORG/projectsV2/NUMBER/fields。GraphQL 可用 gh api graphql -f query='...' -f org=ORG -F number=NUMBER。内建工作流可自动按过滤条件添加条目、关闭时设置状态、自动归档、把子议题加入父项目,无需令牌或 Actions 分钟数;需要跨项目逻辑、外部数据、计算字段值或定时汇总时再用 Actions。用 GitHub App 安装令牌而非 PAT;GITHUB_TOKEN 无法写组织项目。projects_v2_item webhook 可在条目变化时触发。议题表单可用顶层键直接投放看板:projects: ["octo-org/1", "octo-org/44"]。\n\n限制:资料未提供收费、价格等商业信息;用户拥有的项目无法用现代令牌自动化,组织项目才可驱动;未验证的操作支持需逐一确认。
github-projects
通用与其它
更新于 10-16 08:49