> 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 Action 同步说明

部分同步服务会使用你的 GitHub Action 运行同步任务。这样可以让任务在独立环境中执行，便于查看日志，也能减少服务器排队。

## 什么时候需要绑定 GitHub

如果插件在运行前提示绑定 GitHub，就按提示完成绑定。

已经在使用 NotionHub、还没有绑定 GitHub 的老用户，可以按照 [Notionhub 绑定 Github 指南](https://www.notionhub.app/docs/github-binding.md) 完成绑定。新用户请查看对应服务的使用教程。

绑定后，NotionHub 会在你的 GitHub 账号下创建或更新 `notionhub-runner` 仓库，并为已配置的同步服务生成对应的 Action。

如果插件没有提示绑定 GitHub，可以继续按当前流程使用。

## GitHub Action 会做什么

Telegram 是事件型特例：`telegram.yml` 没有定时或手动同步入口，只会在 Bot 收到超过 20 MiB 的附件时自动触发。触发参数只有随机 `task_id`；Action 通过 OIDC 领取一次任务所需的媒体票据和 Notion 凭证，再以 10 MiB 分片上传。日志、Step Summary、Artifact 和 cache 不保存消息正文、文件名、Telegram 标识或访问凭证，临时文件在运行结束时清理。

一次同步通常会经历这些步骤：

- 检查本次运行是否有权限。
- 准备当前服务所需配置。
- 下载同步程序。
- 按服务模块同步数据到 Notion。
- 在运行日志中记录成功、失败或需要重新登录的提示。

一些服务会拆成多个 Job，例如微信读书会分别同步书籍和阅读时长。多个 Job 会按顺序执行，不会同时写入同一份数据。

## 会泄露隐私吗

NotionHub 会尽量把敏感信息写入 GitHub Secret，而不是直接展示在日志中。

敏感信息包括：

- Notion Token
- 第三方平台 Cookie 或 Token
- 激活码
- 通知 Webhook
- 手机号、邮箱等账号信息

请不要把 GitHub Action 日志公开发到社区或群里。如果需要技术支持，可以只发送 Action 链接和错误截图。

## 如何查看运行结果

打开你的 GitHub 仓库：

```text
https://github.com/<你的 GitHub 用户名>/notionhub-runner/actions
```

点击最近一次运行，可以看到每个 Job 的状态。

常见结果：

- 绿色对勾：同步成功。
- 红色叉号：同步失败，需要查看错误提示。
- 黄色圆点：正在运行。
- 灰色取消：任务被取消，可能是你触发了新的同步。

## 为什么会自动取消旧任务

NotionHub 同一个服务同一时间只允许一个任务运行。

如果你在旧任务还没结束时再次点击「开始同步」，新任务会取消旧任务。这是为了避免多个任务同时写入 Notion，产生重复数据。

## 免费体验和 GitHub Action

免费体验用户也可能会使用 GitHub Action。

如果免费体验次数已用完，Action 会在前置检查阶段停止，并提示购买激活码，不会继续下载或运行同步程序。

购买说明见 [获取激活码](https://www.notionhub.app/docs/get-activation-code.md)。

## 开源免费版

微信读书、豆瓣、小宇宙和 Keep 另有独立的开源免费版。免费版与 Pro 版使用同一个 `notionhub-runner` 仓库，但使用不同 Workflow 和 Secret：

- 免费版直接拉取固定版本的公开源码，不下载 NotionHub 私有 Runner。
- 免费任务运行期间不请求 NotionHub Worker，不校验激活码，也不上报结果。
- 免费版默认每天定时运行，也可以从插件打开对应 Action 手动运行。
- 免费与 Pro 共用服务级并发锁，同一个服务不会同时写入 Notion。
- Runner 仓库和已开启的热力图文件是公开的，GitHub Repository Secrets 不公开。

免费版需要在插件中重新配置一次，不能自动读取你以前 fork 仓库中的 Secret。

## 常见问题

### 可以删除 notionhub-runner 仓库吗？

不建议删除。删除后，已经配置好的 GitHub Action、Secret 和运行记录都会丢失。

如果确实删除了，可以回到插件重新绑定 GitHub 并重新生成配置。

### 可以手动修改 GitHub Secret 吗？

不建议手动修改。插件保存配置、重新登录或重新复制模板后，会自动更新需要的 Secret。

手动修改可能导致预检通过但运行失败，或者被后续配置校准覆盖。

### 可以自己点 GitHub 里的 Run workflow 吗？

Pro 版一般建议从插件点击「开始同步」。插件会先检查登录状态、Notion 模板和试用次数，再触发 GitHub Action。

开源免费版的插件按钮只负责打开 Actions 页面，可以直接点击 `Run workflow`；Pro 版直接在 GitHub 运行可能跳过插件侧提示，遇到错误时不容易理解。

### GitHub Action 很慢怎么办？

GitHub Action 的网络速度不稳定，尤其是下载第三方音频、视频或大量图片时会比较慢。

可以先关闭大文件上传，只同步文字、链接、封面等核心数据。
