GitHub 问题
修复企业托管账户上 GitHub App 反复安装、组织和仓库缺失、Webhook 失败、权限错误以及分支不匹配的问题。
大多数 GitHub 集成问题都源于权限、Webhook 失败或分支不匹配。
设置期间未显示组织
入门文档流程会列出您的 GitHub 组织。选择一个组织用于存放新仓库。该列表来自 GitHub 的 OAuth API。在以下两种情况下,GitHub 会从该列表中隐藏某个组织:
- OAuth 应用限制:您的组织限制第三方应用访问(这是新组织的 GitHub 默认设置),且尚未批准 Jamdesk。
- SAML SSO:您的组织要求先进行 SAML 身份验证,API 才会返回该组织。
立即批准 Jamdesk:
- 点击组织选择器下方的 grant Jamdesk access on GitHub(或前往 GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk)
- 在 Organization access 下,点击您组织旁边的 Grant
- 返回 Jamdesk 设置流程,点击 refresh the list。您的组织会立即出现
成员(非所有者)看到的是 Request 按钮。点击后会向组织管理员发送批准请求。
向管理员发送批准请求:
- 前往 GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk
- 在 Organization access 下,点击您组织旁边的 Request。这会通知您的组织管理员
- 管理员在组织的 Settings → Third-party access → OAuth application policy 中批准(待处理的请求会显示 Approve 按钮)
- 返回 Jamdesk 设置流程,点击 refresh the list。您的组织现在应该会出现
有关详细步骤,请参阅 GitHub 指南:为您的组织批准 OAuth 应用。
在设置时选择您的个人账户,即可跳过管理员批准。之后将仓库转移到您的组织:
- 使用您的个人账户完成 Jamdesk 设置
- 前往 GitHub 上创建的仓库
- 打开 Settings → General → Danger Zone
- 点击 Transfer,并选择您的组织作为目标
- 在 Jamdesk 中,从您项目的 Settings 页面断开并重新连接该仓库
断开并重新连接会生成新的文档 URL(例如 your-project.jamdesk.app 可能会改变)。如果您已经分享过 URL 或设置了自定义域名,请在断开连接前联系支持。我们可以保留您的配置。
如果您的公司管理您的 GitHub 账户,此方法将无法使用。请改为参阅企业托管 GitHub 账户。
公司托管的 GitHub 账户
GitHub 会阻止在企业托管账户上安装应用(GitHub 称之为 Enterprise Managed Users,即 EMU)。只有组织才能安装应用。如果没有组织,点击 GitHub 上的 Install 会将您带回 Jamdesk 应用页面。Jamdesk 注册时会显示"您的组织管理此 GitHub 账户"。
托管用户名以下划线和公司代码结尾,例如 jsmith_acme。GitHub 在其托管用户账户页面中说明了相关限制。
请通过以下方案之一解决。
- 请企业所有者创建一个组织,入口在您企业的 Organizations 标签页。请他们允许您在其中创建仓库。
- 将您的文档仓库转移到该组织。在仓库中,前往 Settings,点击底部的 Transfer,然后选择新组织。
- 在 Jamdesk 中,点击 Connect an existing repository(或项目设置中的 Install GitHub App)。在 GitHub 上选择该组织,选择 Only select repositories,勾选您的仓库并完成安装。
如果 GitHub 显示的是 Request 而不是 Install,组织所有者会收到批准邮件。他们批准后,再次点击 Jamdesk 按钮即可。
当您的公司无法添加组织时使用此方法。请先咨询您的 GitHub 管理员。文档将存放在您公司 GitHub 之外。
- 在无痕浏览器窗口中,使用个人账户登录 GitHub(或创建一个)。
- 在该账户上创建一个空的私有仓库。
- 将文档副本推送到该仓库。GitHub 无法将仓库从托管企业中转出。
git remote set-url origin https://jsmith@github.com/jsmith/product-docs.git
git push -u origin main保留 URL 中的 jsmith@,以便 Git 要求输入您个人账户的登录信息。
- 在 Jamdesk 中,点击 Connect an existing repository(或项目设置中的 Install GitHub App),在您的个人账户上安装 Jamdesk,然后选择该仓库。
托管账户无法向企业外的仓库推送内容。每位文档编辑者都需要一个个人 GitHub 账户。请将他们作为协作者添加到仓库中。
未显示仓库
如果您的仓库没有出现在列表中:
- 前往 GitHub → Settings → Applications → Jamdesk
- 确认该仓库已授予访问权限
- 点击 Configure 以添加更多仓库
对于组织仓库:
- 组织管理员必须批准 Jamdesk
- 前往组织设置 → Third-party access
- 批准 Jamdesk 的访问请求
私有仓库需要 GitHub 授权。如有需要,请重新授权 Jamdesk。
未触发构建
如果推送未触发构建:
- 前往 GitHub 上的您的仓库
- 打开 Settings → Webhooks
- 找到 Jamdesk 的 Webhook
- 在 "Recent Deliveries" 中检查错误
构建仅会在您配置的分支上触发。请在 Jamdesk 的 Settings 中检查。
如果构建显示失败,并提示推送者不是成员,请在 Project Settings → Members 中邀请其加入,或让其关联其 GitHub 账户。参见构建未触发。
- 前往 Jamdesk 中的项目 Settings
- 点击 Re-sync GitHub
Webhook 错误
404 Not Found
无法访问 Webhook 端点。
解决方法: 在项目设置中重新同步 GitHub 连接。
401 Unauthorized
身份验证失败。
解决方法:
- 前往您的 GitHub 账户设置
- 打开 Applications → Authorized OAuth Apps
- 撤销 Jamdesk 的授权
- 在 Jamdesk 设置中重新授权
500 Server Error
Jamdesk 临时出现问题。
解决方法: 等待几分钟后重新推送,或手动触发重新构建。
权限错误
构建期间出现 "Repository not found":
- 该仓库可能已被删除或重命名
- Jamdesk 可能已失去访问权限
- 请重新授权您的 GitHub 连接
分支问题
构建了错误的分支
请在 Settings → Repository 中检查您配置的分支。
分支已重命名或删除
请将分支设置更新为新的分支名称。
