Jamdesk Documentation logo

GitHub 问题

解决公司管理账户中的 GitHub App 安装循环、组织和仓库缺失、Webhook 失败、权限错误及分支不匹配问题。

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

设置期间未显示组织

在入门文档流程中,Jamdesk 会显示你的 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 不允许你在个人账户上安装应用,只能在组织中安装。如果没有可供你使用的组织,在 GitHub 上点击 Install 只会将你返回 Jamdesk 应用页面。注册期间,Jamdesk 会显示“Your organization manages this GitHub account”。

受管理的用户名以下划线和公司代码结尾,例如 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
重新同步连接
  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 和错误消息

相关文章

错误参考

完整的错误代码列表

联系支持团队

升级处理未解决的问题