Jamdesk Documentation logo

GitHub 问题

修复企业托管账户上 GitHub App 反复安装、组织和仓库缺失、Webhook 失败、权限错误以及分支不匹配的问题。

大多数 GitHub 集成问题都源于权限、Webhook 失败或分支不匹配。

设置期间未显示组织

入门文档流程会列出您的 GitHub 组织。选择一个组织用于存放新仓库。该列表来自 GitHub 的 OAuth API。在以下两种情况下,GitHub 会从该列表中隐藏某个组织:

  • OAuth 应用限制:您的组织限制第三方应用访问(这是新组织的 GitHub 默认设置),且尚未批准 Jamdesk。
  • SAML SSO:您的组织要求先进行 SAML 身份验证,API 才会返回该组织。

立即批准 Jamdesk:

  1. 点击组织选择器下方的 grant Jamdesk access on GitHub(或前往 GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk)
  2. 在 Organization access 下,点击您组织旁边的 Grant
  3. 返回 Jamdesk 设置流程,点击 refresh the list。您的组织会立即出现

成员(非所有者)看到的是 Request 按钮。点击后会向组织管理员发送批准请求。

向管理员发送批准请求:

  1. 前往 GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk
  2. 在 Organization access 下,点击您组织旁边的 Request。这会通知您的组织管理员
  3. 管理员在组织的 Settings → Third-party access → OAuth application policy 中批准(待处理的请求会显示 Approve 按钮)
  4. 返回 Jamdesk 设置流程,点击 refresh the list。您的组织现在应该会出现

有关详细步骤,请参阅 GitHub 指南:为您的组织批准 OAuth 应用。

在设置时选择您的个人账户,即可跳过管理员批准。之后将仓库转移到您的组织:

  1. 使用您的个人账户完成 Jamdesk 设置
  2. 前往 GitHub 上创建的仓库
  3. 打开 Settings → General → Danger Zone
  4. 点击 Transfer,并选择您的组织作为目标
  5. 在 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 在其托管用户账户页面中说明了相关限制。

请通过以下方案之一解决。

  1. 请企业所有者创建一个组织,入口在您企业的 Organizations 标签页。请他们允许您在其中创建仓库。
  2. 将您的文档仓库转移到该组织。在仓库中,前往 Settings,点击底部的 Transfer,然后选择新组织。
  3. 在 Jamdesk 中,点击 Connect an existing repository(或项目设置中的 Install GitHub App)。在 GitHub 上选择该组织,选择 Only select repositories,勾选您的仓库并完成安装。

如果 GitHub 显示的是 Request 而不是 Install,组织所有者会收到批准邮件。他们批准后,再次点击 Jamdesk 按钮即可。

当您的公司无法添加组织时使用此方法。请先咨询您的 GitHub 管理员。文档将存放在您公司 GitHub 之外。

  1. 在无痕浏览器窗口中,使用个人账户登录 GitHub(或创建一个)。
  2. 在该账户上创建一个空的私有仓库。
  3. 将文档副本推送到该仓库。GitHub 无法将仓库从托管企业中转出。
git remote set-url origin https://jsmith@github.com/jsmith/product-docs.git
git push -u origin main

保留 URL 中的 jsmith@,以便 Git 要求输入您个人账户的登录信息。

  1. 在 Jamdesk 中,点击 Connect an existing repository(或项目设置中的 Install GitHub App),在您的个人账户上安装 Jamdesk,然后选择该仓库。

托管账户无法向企业外的仓库推送内容。每位文档编辑者都需要一个个人 GitHub 账户。请将他们作为协作者添加到仓库中。

未显示仓库

如果您的仓库没有出现在列表中:

  1. 前往 GitHub → Settings → Applications → Jamdesk
  2. 确认该仓库已授予访问权限
  3. 点击 Configure 以添加更多仓库

对于组织仓库:

  1. 组织管理员必须批准 Jamdesk
  2. 前往组织设置 → Third-party access
  3. 批准 Jamdesk 的访问请求

私有仓库需要 GitHub 授权。如有需要,请重新授权 Jamdesk。

未触发构建

如果推送未触发构建:

1
检查 Webhook
  1. 前往 GitHub 上的您的仓库
  2. 打开 Settings → Webhooks
  3. 找到 Jamdesk 的 Webhook
  4. 在 "Recent Deliveries" 中检查错误
2
验证分支

构建仅会在您配置的分支上触发。请在 Jamdesk 的 Settings 中检查。

3
检查推送者

如果构建显示失败,并提示推送者不是成员,请在 Project Settings → Members 中邀请其加入,或让其关联其 GitHub 账户。参见构建未触发。

4
重新同步连接
  1. 前往 Jamdesk 中的项目 Settings
  2. 点击 Re-sync GitHub

Webhook 错误

404 Not Found

无法访问 Webhook 端点。

解决方法: 在项目设置中重新同步 GitHub 连接。

401 Unauthorized

身份验证失败。

解决方法:

  1. 前往您的 GitHub 账户设置
  2. 打开 Applications → Authorized OAuth Apps
  3. 撤销 Jamdesk 的授权
  4. 在 Jamdesk 设置中重新授权

500 Server Error

Jamdesk 临时出现问题。

解决方法: 等待几分钟后重新推送,或手动触发重新构建。

权限错误

构建期间出现 "Repository not found":

  • 该仓库可能已被删除或重命名
  • Jamdesk 可能已失去访问权限
  • 请重新授权您的 GitHub 连接

分支问题

构建了错误的分支

请在 Settings → Repository 中检查您配置的分支。

分支已重命名或删除

请将分支设置更新为新的分支名称。

仍有问题?

联系支持

请附上您的仓库 URL 和错误信息

相关文章

错误参考

完整错误代码列表

联系支持

升级未解决的问题