Macro 的 GitHub 集成到底做了什么：分支、PR 合并与任务状态自动同步的边界在哪
任务板和代码仓库两张皮，是几乎所有团队都踩过的事。任务在项目管理工具里躺着，分支在 GitHub 上开了，PR 也合了，但没人回去把那张卡片从”进行中”拖到”完成”。等到周会上对齐进度，看板上的状态已经落后现实好几天。
Macro 把 GitHub 集成放在这个位置上：它要解决的不是”让你在任务里写代码”，而是”让任务状态自己跟上代码的进度”。官方文档对这条能力的描述相当克制——原话是让 pull request 关联到任务，让任务状态在你发版的过程中自己更新。
这篇只讲官方文档写明的部分：哪三个动作会触发状态变化、PR 在 Macro 里被当成什么、从 MCP 一侧能不能动这些任务，以及自托管时官方专门提了一句什么。文档没写的（比如 GitHub 之外的代码托管平台、失败重试机制、webhook 细节），这里一个字都不会补。
连接入口：文档里出现了两种路径
先说一个读文档时容易卡住的地方。Macro 的 GitHub 集成页写的是，在 Settings 的 Account 下关联你的 GitHub 账号；而任务页那一节的提示框里写的是，在 Settings → Connections 里关联 GitHub 账号，然后点连接。
两处官方文档给的路径措辞不一致。我们没有安装过这个产品，无法判断是同一个入口的两种叫法，还是文档其中一处没跟上改版——这里只如实记下这个差异，实际操作时以你看到的设置项为准，两条路径都在 Settings 里，不至于找不到。
除此之外，官方对”接入”这件事没有额外的配置说明：没有提到需要填仓库白名单，没有提到需要装 GitHub App 之外的东西，也没有提到组织级授权和个人授权的区别。文档没说，就当它没说，不要按其它工具的经验去推断。
三个动作，三次状态跳转
集成生效之后，真正被自动化的是任务状态。官方给出的映射非常明确：
为任务创建分支 → In Progress（进行中）
打开 Pull Request → In Review（评审中）
PR 合并 → Done（完成）
注意这里的触发点是”为一个任务创建分支”。Macro 提供了一个配套动作：选中任务后，按 shift + cmd + b 复制该任务对应的分支名。也就是说，任务与分支的绑定关系是靠分支名建立的，你得用它给的名字去建分支，这条链路才认得出来。这一点决定了整套自动化的可靠性上限：分支名改了、或者随手起了个别的名字，后面的状态流转就无从谈起。
关于状态命名，文档内部也有一处小小的不统一。任务页列出的四个状态是 Not Started（还没被认领）、In Progress（有人在做）、In Review（做完了等评审）、Completed（已完成）；而 GitHub 集成的描述里，合并后落到的状态写作 Done。这两个词指的应该是同一个终态，但官方文档的两处措辞确实不同。
| 触发动作 | 任务状态（GitHub 集成页口径） | 对应任务页的状态枚举 |
|---|---|---|
| 创建分支 | In Progress | In Progress |
| 开 PR | In Review | In Review |
| PR 合并 | Done | Completed |
Macro 对任务字段的设计思路是”够用就好”：官方明确写了，因为任务本来就长在工作区里，不需要额外的标签和分类，只有状态、优先级、负责人三项。这也解释了为什么状态自动化只挑了这三个节点——可动的字段本来就不多。任务模型本身的完整说明可以看 Macro 任务管理怎么用。
关联的 PR 会挂在任务上
状态之外，第二件事是把 PR 的信息带回任务。官方说，关联的 pull request 会直接出现在任务上，带着它的标题、PR 编号和 diff 体积（改动行数规模），任何人看这个任务都能直接跳到代码。此外，每一个关联的 PR 也会列在任务属性面板的 GitHub 分区里。
这个设计的意义在于评审和对齐：看板上一张卡片如果只写着”完成”，别人还得去仓库里翻是哪个 PR；带上编号和改动规模，至少能判断这是个改了两行的配置修正，还是一次大重构。
PR 是 block，所以能被 @提及、被 agent 读
这是 Macro 这套东西里比较特别的一环。官方原话是：pull request 和 Macro 里的其它东西一样，也是 block——你可以在频道和文档里 @提及它们，agent 也可以读取它们作为上下文。
要理解这句话的分量，得先知道 block 在 Macro 里意味着什么：它是整个产品共用的那层数据抽象，邮件、任务、文档、频道消息都是 block，所以它们之间可以互相引用、互相搜索。具体机制见 Macro 的 blocks 数据模型。
PR 进了这一层，实际效果是：
- 在文档里写方案时，可以直接 @ 上那个 PR，而不是贴一条 GitHub 链接；
- 在频道里讨论时，PR 作为可引用的实体存在；
- agent 在处理相关问题时，能把 PR 当作上下文读进去。
任务本身也是 markdown 实体，@提及后渲染成一个”活的”标签，会跟着任务的状态和标题同步更新，点一下就跳到任务。PR 的引用效果，官方没有逐条描述到这个粒度，只写了”可以 @提及、agent 可以读取”，更细的就不替它补了。
从编辑器一侧动任务：MCP
如果你的活主要在编辑器里干，Macro 提供了 MCP 服务端。官方写明它可以让 Claude Code、Codex、Cursor 这类 AI 客户端直接操作任务，连接方式是去 Settings → MCP server 用 Macro 账号授权一次，并且明确说了 MCP 访问包含在每个套餐里，免费版也包括在内。
任务相关的 MCP 能力，官方列了四项：
| MCP 操作 | 说明（官方措辞） |
|---|---|
| Create a task | 新建一个任务 |
| Find your tasks | 找到你的任务 |
| Read a task | 读取某个任务 |
| Update a task | 更新任务 |
官方举的用法是：不离开编辑器就建一个任务、给任务列表做分诊、或者把某件事挪到 “In Review”，改动会实时反映在 Macro 里。
把这条和 GitHub 集成放在一起看，就有两条并行的状态来源：一条是分支/PR 自动推的，一条是你（或你的 agent）通过 MCP 手动改的。文档没有说明两者冲突时以谁为准——比如你先用 MCP 把任务标成 In Review，之后 PR 才合并，最终状态怎么定，官方文档未说明。真要依赖这套自动化，这是需要自己先验证的点。MCP 服务的整体能力范围见 Macro 的 MCP 服务能做什么。
自托管的一句提示
Macro 是可以自托管的，但官方在应用获取页留了一条给自托管者的注记，值得单独拎出来：托管版（hosted version）才是拿到了 Apple、Google Mail 和 GitHub 授权的那一份，自托管部署意味着什么，官方让你去看 FAQ。
换句话说，GitHub 集成能不能在你自己搭的实例上原样跑起来，官方在这里没有打包票，而是把口径指向了另一篇文档。如果你的计划是自托管 + 依赖 PR 自动流转任务状态，这句提示应该排在验证清单的第一条。关于客户端形态与平台差异，可以看 Macro 的应用体系。
它不解决什么
按官方文档的覆盖范围，下面这些是这套集成明确没提供、或者根本没提到的：
- 只写了 GitHub。GitLab、Gitee、自建 Git 服务在文档里没有出现，不要假设同样支持。
- 只覆盖三个节点。分支创建、PR 打开、PR 合并。PR 被关闭而非合并、被 revert、多个 PR 对一个任务，官方文档没有说明处理方式。
- 绑定靠分支名。任务与代码的关联建立在按约定命名的分支上，不走分支的改动（直接 push 主干、在别人仓库开 PR）自然接不上。
- 不是双向控制代码。它把代码的进展映射成任务状态，反过来在任务里改状态会不会影响 PR，文档没写。
- 自托管边界待确认。授权归属那条注记已经说明官方对自托管场景另有口径。
真正适合上这套东西的，是任务规模不大、状态字段本来就简单、团队愿意用规定分支名开工的场景——它省掉的是”回去拖卡片”这一下，不是项目管理本身。如果你的流程里状态有七八个、每个状态背后还挂着审批，那 Macro 这套只有三档的自动化，能接住的部分很有限。
延伸阅读
- 从头读起：Macro 是什么：邮件、任务、文档、CRM 共用一个双向数据库的开源工作区
- 本专题共 40 篇，完整分组目录见专题页
- Macro 的应用体系与扩展点：MCP、GitHub 与自托管到底能接什么
- Macro 的安全与数据处理官方说明：数据放哪、谁能看到、AI 会不会拿去训练
本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、
MCP 工具参考与自托管说明整理，核对日 2026-08-17。
我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感；
官方标注为计划中的能力文中已如实标明，不代表当前可用。
价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。