> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub 权限

> 在您选择的权限级别下，授予客户对私人 GitHub 仓库的协作者访问权限，并在取消时自动撤销。

<Info>
  GitHub 权限将付费客户添加为私人仓库的协作者。您可以选择权限级别 (`pull`, `push`, `triage`, `maintain`, 或者 `admin`)，由 Dodo Payments 处理邀请、接受跟踪和取消时的移除。
</Info>

## 交付内容

* 客户通过 OAuth 流程被邀请到您的 GitHub 仓库，将其 GitHub 账户链接到购买上。
* 一旦他们接受，GitHub 将根据配置的权限级别授予他们协作者访问权限。
* 取消、退款或手动撤销会移除协作者。

常见用途包括源码可用产品、付费模板、课程代码仓库和客户 SDK 阶段性访问。

## 连接 GitHub

<Steps>
  <Step title="Open Entitlements">
    在您的 Dodo Payments 仪表板中，转到 **Entitlements** 并点击 **+** 开始新的权限设置。
  </Step>

  <Step title="Pick GitHub">
    选择 **GitHub Access** 作为集成。如果 GitHub 尚未连接，系统会提示您 **连接 GitHub**。

    <Frame caption="Connect GitHub prompt before the install handoff.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/github/connect-prompt.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=8a836c94099accdb2b3dc31c22d0e11b" alt="新权限面板提示商家连接 GitHub" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1129" data-path="images/entitlements/github/connect-prompt.png" />
    </Frame>

    点击后将在新标签页中打开 GitHub。登录，然后在拥有仓库的组织或用户账户上安装 Dodo Payments GitHub 应用。您可以授予 **所有仓库** 访问权限或仅限您打算限制访问的仓库。

    <Frame caption="GitHub Install & Authorize page — choose which repositories the app can manage.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/github/oauth-install.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=0788d3f6e9df8a087de824967f09c215" alt="GitHub 安装和授权页面，包含所有仓库和仅选择仓库选项" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1120" data-path="images/entitlements/github/oauth-install.png" />
    </Frame>

    当 GitHub 重定向返回时，您将看到账户已连接的确认信息。

    <Frame caption="Account connected — return to the Dodo Payments dashboard to continue.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/github/connected.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=ee3c87c3b3917f473ff3d376dfdc6494" alt="GitHub 访问成功连接确认页面" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1137" data-path="images/entitlements/github/connected.png" />
    </Frame>
  </Step>

  <Step title="Pick a repository and permission">
    回到仪表板，选择应授予权限的 **仓库** 并选择 **权限** 级别。仓库选择器仅显示 GitHub 应用有访问权限的仓库。给权限命名并点击 **Create Entitlement**。

    <Frame caption="Creating a GitHub entitlement. Pick the repository and the permission you want customers to receive.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/github/create.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=722e925ec5158a5d16c58213132ccb9d" alt="GitHub 权限表单，包含已连接的 GitHub Access、仓库选择器、权限下拉选项和名称字段" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1130" data-path="images/entitlements/github/create.png" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    保存并将权限附加到任何产品。购买该产品的客户将在交付时收到 GitHub 邀请。
  </Step>
</Steps>

## 权限级别

GitHub 的标准仓库权限适用：

| 权限         | 最适合                        |
| ---------- | -------------------------- |
| `pull`     | 只读访问。客户可以克隆、拉取和查看仓库。       |
| `triage`   | 读取访问权限加上管理问题和拉取请求的能力。      |
| `push`     | 读 + 写访问。客户可以推送分支和打开拉取请求。   |
| `maintain` | 推送访问权限加上对仓库设置的管理（不包括敏感设置）。 |
| `admin`    | 对仓库的完全控制。谨慎使用。             |

<Warning>
  授予适合您使用案例的 **最低特权**。大多数付费内容场景只需要 `pull`。
</Warning>

## 客户流程

1. 客户完成结账。
2. Dodo Payments 创建处于 `pending` 状态的授权，并提供 `oauth_url` 供客户链接其 GitHub 账户。
3. 客户通过电子邮件或客户门户中的链接进行授权。
4. Dodo Payments 邀请客户的 GitHub 账户按配置的权限访问仓库。创建邀请后，授权移至 `delivered`。
5. 如果订阅被取消、退款或撤销，客户将被移除为协作者。

## 所需配置

| 字段           | 必需 | 描述                                                  |
| ------------ | -- | --------------------------------------------------- |
| `target_id`  | 是  | 邀请客户到的仓库。仪表板的仓库选择器会为您填写这一项。                         |
| `permission` | 是  | 其中一个 `pull`, `push`, `triage`, `maintain`, `admin`。 |

## API 创建

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Code Share Repository',
    integration_type: 'github',
    integration_config: {
      target_id: 'acme/private-sdk',
      permission: 'pull',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Code Share Repository",
      integration_type="github",
      integration_config={
          "target_id": "acme/private-sdk",
          "permission": "pull",
      },
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Code Share Repository"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeGithub),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigGitHubConfigParam{
        TargetID:   dodopayments.F("acme/private-sdk"),
        Permission: dodopayments.F("pull"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

标准的 [`entitlement_grant.*` webhook 事件](/developer-resources/webhooks/intents/entitlement-grant) 涵盖了 GitHub 流程：

* `entitlement_grant.created` 包含用于 GitHub 授权的 `oauth_url`。
* `entitlement_grant.delivered` 在协作者邀请创建后触发。
* `entitlement_grant.failed` 与 `error_code: "github_permission_denied"`（一类）一同触发，如果 GitHub 应用失去了仓库的访问权限。

## 故障排除

<AccordionGroup>
  <Accordion title="Repository picker is empty">
    Dodo Payments GitHub 应用必须安装在拥有仓库的组织或用户上。打开 **Entitlements → Integrations → GitHub**，重新安装应用，确保授予相关仓库的访问权限。
  </Accordion>

  <Accordion title="Grant fails with permission_denied">
    GitHub 应用的安装不再有对仓库的访问权限，或仓库已重命名/转移。重新授予应用访问权限，下次重新授权将成功。
  </Accordion>

  <Accordion title="Customer hasn't accepted the invite">
    客户必须从通知页面或点击电子邮件中的链接接受 GitHub 邀请。在他们接受之前，他们保持“已邀请”，但无法克隆仓库。在 Dodo Payments 的视角中，授权仍为 `delivered`；邀请是我们发出的。
  </Accordion>
</AccordionGroup>