> For AI agents: the complete documentation index is available at https://www.notionhub.app/llms.txt, the full documentation bundle is available at https://www.notionhub.app/llms-full.txt.

# GitHub Star 同步到 Notion

NotionHub 可以把当前 GitHub 账号 Star 的仓库单向同步到 Notion，并保留 GitHub Lists 分类。同步会维护仓库、作者、分类以及全部、年、月、周、日关系，不会把 Notion 中的修改反向写回 GitHub。

## 使用前准备

- 已安装 NotionHub 浏览器插件并登录 Notion。
- 已在 NotionHub 连接 GitHub Runner。这个连接由所有需要 GitHub Actions 的服务共用，不需要为 GitHub Star 再填写 token。
- 已购买 GitHub 同步激活码，或仍有一次免费体验。

## 配置步骤

### 1. 复制 Notion 模板

在插件服务列表打开「GitHub」，点击「复制 Notion 模板」并完成 Notion 授权。模板包含以下数据库：

| 数据库        | 内容                           |
| ---------- | ---------------------------- |
| 仓库         | Star 仓库元数据、收藏状态、收藏时间和分类关系    |
| 作者         | GitHub Owner 名称、链接、头像和类型     |
| 分类         | GitHub Lists 名称、描述、私有状态和有效状态 |
| 全部、年、月、周、日 | 按收藏时间建立日期关系                  |

可以调整视图、增加自己的属性和页面正文，但不要删除或改名模板已有字段、关系和 GitHub Node ID。

### 2. 确认 GitHub 连接

如果账号页已经显示 GitHub 已连接，复制模板后可以直接点击「开始同步」，不需要重复授权。未连接或授权已失效时，插件会打开现有 GitHub Runner OAuth 流程；完成一次授权后会同时用于 Runner 和 Star 数据读取。

NotionHub 保持现有 `repo workflow` scope，不扩大额外权限。该授权允许读取当前账号可见的公开和私有 Star 仓库。真实 GitHub OAuth token 只加密保存在 Integration Worker，不会写入你的 `notionhub-runner` 仓库 Secret。

### 3. 开始同步

点击「开始同步」会运行 `github.yml`。默认每天 00:00（北京时间）自动同步，也可以在插件或 GitHub Actions 手动运行。

免费体验只同步按收藏时间倒序最近的 20 个仓库；激活后会读取完整当前 Star 状态。普通同步只写入新增或变化的数据，全量同步会刷新所有受管字段和当前分类关系。

## 同步规则

- 仓库以 GitHub Node ID 去重，仓库改名不会重复创建页面。
- 一个仓库可以同时属于多个 Lists；没有 List 的仓库保持空分类。
- 取消 Star 后页面会保留，并设置「已收藏 = 否」和首次检测到的取消收藏时间；已有分类关系也会保留。
- 重新 Star 后会恢复收藏状态、清空取消收藏时间，并刷新当前 Lists 分类。
- List 重命名会更新原页面；成功读取完整 Lists 后，已删除的 List 会设置「有效 = 否」。
- 同步只更新模板受管属性，不修改你增加的属性、页面正文或笔记。

## Lists 降级说明

GitHub Lists 使用 GraphQL 能力，可能独立于 Star 接口暂时不可用。遇到 Lists 预览能力、分页或限流错误时，NotionHub 会继续同步 Stars，并保留 Notion 中已有分类关系，不会因为一次能力异常清空分类。

## 常见问题

### 为什么私有仓库没有同步

确认该仓库对当前 OAuth 用户可见，并重新连接 GitHub。组织策略可能限制第三方 OAuth 访问私有仓库；这种情况需要在 GitHub 组织授权页面允许访问后重试。

### 为什么分类没有更新

先查看 `github.yml` 日志中是否有 Lists capability warning。如果 Stars 正常而 Lists 暂时不可用，旧分类会被安全保留；稍后重新运行即可。

### 为什么取消 Star 的页面还在

这是预期行为。同步不会删除或归档取消收藏的页面，以免丢失你在 Notion 中增加的笔记和属性。可以使用「已收藏」筛选当前收藏。

### 如何查看同步失败原因

打开 `notionhub-runner` 仓库的 Actions，进入 `github.yml` 对应运行。保留 HTTP 状态、错误类型和失败步骤即可，不要公开粘贴 GitHub token、Notion token、激活码或完整 Action Secret。
