#Notionhub 绑定 Github 指南

这篇指南面向已经在使用 NotionHub、还没有绑定 GitHub 的老用户。新用户请查看对应服务的使用教程，其中已经包含 GitHub 绑定步骤。

最近使用 NotionHub 时，你可能会看到“连接 GitHub”的提示。绑定后，同步任务会通过 GitHub Actions 执行，每一次运行都有状态、有进度、有记录，出现问题时也能知道具体卡在哪一步。

#为什么改用 GitHub Actions

过去用户点击同步后，很难准确知道任务有没有开始、正在处理什么、还要等多久。同步失败时，也缺少一份可以回看的完整运行记录。

改用 GitHub Actions 后，这些信息都变得可见：

• 运行状态：排队、运行中、成功、失败或取消。
• 执行进度：当前运行到哪个 Job、哪个步骤。
• 历史记录：每次同步的时间、耗时和结果都会保留。
• 错误位置：失败步骤和错误提示可以直接查看。

同一个服务如果在旧任务未结束时再次运行，新任务会自动取消旧任务，避免两个任务同时写入 Notion 造成重复数据。因此偶尔看到灰色的 Cancelled，不一定是业务错误。

#老用户如何绑定 GitHub

#第一步：打开账号页面

点击浏览器工具栏里的 NotionHub 图标，打开插件，再切换到左侧的“账号”页面。

#第二步：登录原来的 Notion 账号

如果还没有登录 Notion，先点击 Notion 登录入口，使用之前配置同步服务时的 Notion 账号完成登录和授权。已经登录的用户可以直接进行下一步。

#第三步：连接 GitHub

点击“连接 GitHub”，在跳转的页面登录并完成授权。

如果没有 GitHub 账号，可以使用邮箱注册一个新账号，也可以直接使用 Google 或苹果账号登录。

回到插件后，看到“GitHub 已连接”，就说明绑定成功。这个连接状态对所有同步服务共用，不需要为每个服务重复绑定。

绑定完成后，回到原来使用的服务，按页面提示发起同步。

#绑定后会创建什么

首次完成 GitHub 授权后，NotionHub 会在你的账号下创建或更新一个名为 notionhub-runner 的仓库，并为已经配置的服务生成对应的 Workflow。

仓库地址通常是：

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

这个仓库会保存 Workflow 文件和运行记录。GitHub 只需授权一次，后续微信读书、Keep、B 站、YouTube 等服务共用同一个 Runner 仓库，不需要每个服务重复绑定。

#公开仓库会不会泄露账号信息

notionhub-runner 仓库本身可以公开查看，但敏感配置不会直接写在 Workflow 或运行日志里。

Notion Token、第三方平台 Cookie 或 Token、激活码等信息会存放在 GitHub Repository Secrets 中。Secrets 的值不会显示在公开仓库页面，也不能从 GitHub 页面读取出来。

仍然建议注意两点：

1. 不要手动把 Cookie、Token、密码粘贴到仓库文件或 Issue 中。
2. 寻求技术支持时，只发送 Actions 运行链接或错误截图，不要复制完整敏感配置。

#如何查看运行状态

打开你的 notionhub-runner 仓库，点击顶部的 Actions。

列表中的常见状态：

• 绿色对勾：同步成功。
• 黄色圆点：正在排队或运行。
• 红色叉号：同步失败，需要查看错误步骤。
• 灰色图标：任务被取消，常见原因是新任务替代了旧任务。

点进一次运行，可以看到多个 Job 和每一步的状态。不同服务的 Job 数量不同，例如视频服务可能把数据同步和媒体上传拆开执行。

#运行失败怎么处理

先点开红色 Job，再展开带红叉的步骤。大多数问题可以归为几类：

• 第三方账号登录已过期：回插件重新连接账号。
• Notion 授权已过期：重新授权原来的模板。
• 模板结构不完整：确认复制了正确模板，且没有删除必需数据库。
• 免费体验次数已用完：获取对应服务的激活码并激活。
• GitHub 环境或第三方网络异常：稍后从插件重新运行一次。

遇到无法判断的错误，把本次 Actions 运行链接和红色步骤截图发给技术支持即可。运行链接比一句“同步失败了”包含更多上下文，也能明显缩短排查时间。

#常见问题

#可以自己点击 Run workflow 吗？

完整版本通常建议从插件开始同步，因为插件会先做账号、模板和权益检查。直接在 GitHub 点击运行可能跳过这些提示。

开源免费版可以按照插件指引打开 Actions，再手动点击 Run workflow。

#为什么任务显示 Cancelled？

同一个服务不会并发写入 Notion。短时间内重复点击同步时，新的运行会取消旧运行，以最新任务为准。

#可以删除 notionhub-runner 吗？

不建议。删除后 Workflow、Secrets 和历史运行记录都会丢失。如果已经删除，需要回到插件重新连接 GitHub 并重新保存服务配置。

#GitHub Actions 会一直运行吗？

不会。每次同步完成后任务会自动结束。耗时主要取决于数据量，以及图片、音频、视频等媒体文件的下载和上传速度。

#最后

GitHub Actions 的价值不是增加一步授权，而是让同步从“点完以后只能等”变成一个可以确认、可以追踪、可以排查的过程。

完成一次绑定后，你不需要日常管理仓库。正常使用时仍然从 NotionHub 插件发起同步；只有想看进度、历史记录或排查错误时，再打开 GitHub Actions。

更多运行说明见 GitHub Action 同步说明。