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

# 创建 GitHub App

> 创建 GitHub App,让 Kody 能读取代码库、在 pull request 上评论并接收 webhook —— 含需要授予的具体权限。

如果您想通过 GitHub App 运行 Kody，需要创建一个 GitHub App。此应用使 Kody 能够与您的仓库交互、管理拉取请求并接收 webhooks。

<Note>如果您想为平台用户启用“使用 GitHub 登录”，那是单独的 OAuth App 流程，不会干扰 GitHub App 的权限。本指南专注于功能集成。参见 <a href="/zh/how_to_deploy/platforms/github/github_oauth">GitHub OAuth App</a>。</Note>

## 先决条件

准备好您的应用域名：

* **WEB\_DOMAIN**：您的前端 URL（例如 `https://app.yourdomain.com` 或 `http://localhost:3000`）
* **API\_DOMAIN**：您的后端/API URL（例如 `https://api.yourdomain.com` 或 `http://localhost:3000` 用于单仓库/代理设置）
* **WEBHOOK\_DOMAIN**（可选）：用于 webhook 的公共域名（例如 `https://kodus-webhooks.yourdomain.com`）。如果您在 API 域名上路由 `/.../webhook`，也可以使用 `API_DOMAIN`。

## 步骤 1：创建 GitHub App

1. 在 GitHub 上，转到 **设置** > **开发者设置** > **GitHub Apps**
2. 点击 **新建 GitHub App**
3. 根据您的偏好填写基本信息（名称、主页 URL）

<img src="https://success.skyhighsecurity.com/@api/deki/files/66490/Click_newGithubApp.png?revision=1" alt="GitHub Apps 设置页中的“New GitHub App”按钮" />

## 步骤 2：配置回调和设置 URL

<img src="https://kodus.io/wp-content/uploads/2026/01/githuapp-urls.gif" alt="GitHub App Webhook" />

这一步对于确保安装和重定向正常工作至关重要。填写以下字段，将 `WEB_DOMAIN` 替换为您的实际 URL：

* **回调 URL**：
  ```
  WEB_DOMAIN/api/auth/callback/github
  ```
  此 URL 用于完成授权流程。

* **设置 URL**：
  ```
  WEB_DOMAIN/setup/github
  ```

* 勾选选项：**Redirect on update**（更新时重定向）
  这确保安装应用后，用户被重定向回 Kodus 以完成设置。

## 步骤 3：配置 Webhook

Webhook 通知 Kodus 关于拉取请求中的事件。

<Note>
  Webhook 由独立服务处理（端口 3332）。如果这里使用 API 域名，请确保反向代理将 `/github/webhook` 路径转发到 Webhooks 服务；否则请使用独立的 webhook 域名。
</Note>

* **Webhook URL**：
  ```
  WEBHOOK_DOMAIN/github/webhook
  ```

* 确保 **Active** 选项已勾选

## 配置仓库权限和事件

在 **Repository permissions** 中，根据启用的功能设置以下权限。不要将所有权限都保留为 **No access**。

| Permission    | Access |
| ------------- | ------ |
| Contents      | 只读     |
| Pull requests | 读写     |
| Issues        | 读写     |
| Checks        | 读写     |
| Metadata      | 只读     |

只有需要提交仓库文件的功能才需要 Contents 写权限；读取代码只需只读权限。将 App 安装到目标仓库，修改已有安装的权限后，还需批准新增权限。

订阅 **Pull request**、**Pull request review comment**、**Issue comment** 和 **Push**。当前处理器接受这四类事件，其他事件即使被忽略也可能返回 200。

## 步骤 4：收集凭据并添加到 .env

<img src="https://kodus.io/wp-content/uploads/2026/01/gthubapp-env.gif" alt="GitHub App Webhook" />

现在您需要获取 GitHub 生成的凭据并将其添加到您的 Kodus 环境变量中。

### App ID

在应用"关于"页面的顶部，复制 **App ID**。

添加到您的 `.env`：

```
API_GITHUB_APP_ID=your_app_id_here
```

### Client Secret

转到 **Client secrets** 部分并点击 **Generate a new client secret**。

复制生成的值。

添加到您的 `.env`：

```
API_GITHUB_CLIENT_SECRET=your_client_secret_here
```

### Private Key

滚动到页面底部并点击 **Generate a private key**。

这将下载一个 `.pem` 文件。使用文本编辑器打开此文件并复制整个内容。

添加到您的 `.env`：

```
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
```

### 安装 URL

打开您的 GitHub App，点击 **Install App**。从浏览器地址栏复制安装 URL（形如 `https://github.com/apps/<app-slug>/installations/new`）。

添加到您的 `.env`：

```
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

## 环境变量摘要

最后，您的配置文件应包含：

```bash theme={null}
API_GITHUB_APP_ID=123456
API_GITHUB_CLIENT_SECRET=example_secret_123
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

在 GitHub 上点击 **Save Changes**（保存更改）并重启您的 Kodus 应用程序以应用更改。

## 验证连接

Webhook URL 必须到达 webhooks 服务，而不是前端登录页。只有反向代理将 `/github/webhook` 转发到该服务时，才能使用 `API_DOMAIN`；不能仅凭 `WEB_DOMAIN` 或 200/307 响应判断投递成功。

保持 **Redirect on update** 开启。安装或修改仓库访问范围后，完成通过 **Setup URL** 返回 Kodus 的浏览器流程。成功的 `ping` 或被忽略的 `installation` 事件不会创建 Kodus 集成。

在 Kodus 的 Git Settings 中确认目标仓库已连接。然后创建测试 PR，同时检查 GitHub 投递响应和 Kodus webhooks/worker 日志。若未连接，请检查仓库授权范围、新权限是否批准、Setup URL 和反向代理路由。

[GitHub 注册参考](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).