Onlook GitHub 集成配置指南：从 GitHub App 环境变量到 PKCS8 密钥接入的完整实践

Onlook GitHub 集成配置指南：从 GitHub App 环境变量到 PKCS#8 密钥接入的完整实践

【免费下载链接】onlookThe Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI项目地址: https://gitcode.com/GitHub_Trending/on/onlook

本篇技术指南聚焦 Onlook 开源仓库中的 GitHub 集成包@onlook/github，系统讲解其运行所需的三个核心环境变量（GITHUB_APP_ID、GITHUB_APP_PRIVATE_KEY、GITHUB_APP_SLUG）、私有密钥的 PKCS#8 格式转换流程，并结合仓库源码剖析安装 URL 生成、安装回调处理与 Octokit 鉴权调用的底层实现。读完本文，你将掌握在自托管或本地环境中完整接入 GitHub App 的能力，并能通过源码级理解快速排查常见配置错误。

一、@onlook/github包在 Onlook 中的定位

@onlook/github是 Onlook monorepo（仓库根目录见 package.json）中负责 GitHub 集成的独立包，其入口 packages/github/src/index.ts 统一导出了四个模块：

从 packages/github/package.json 的依赖声明可以看到，该包围绕 Octokit 生态构建：@octokit/auth-app（App 级鉴权策略）、@octokit/rest（GitHub REST API 客户端）、@octokit/app，并使用uuid生成一次性安装状态令牌。包本身是纯 TypeScript 模块（"type": "module"），通过"exports": { ".": "./src/index.ts" }直接以源码形式被其他包引用。

在 Web 端，该包被 apps/web/client/src/server/api/routers/github.ts 的 TRPC Router 实际调用，支撑"从 GitHub 导入项目""校验仓库""列出可访问仓库"等业务流程。因此，配置好本文所述的环境变量是启用这些功能的前提。

二、前置准备：在 GitHub 上创建 GitHub App

按照 packages/github/README.md 与源码推断，接入前需要先在 GitHub 开发者设置中注册一个 GitHub App。注册完成后，你会获得三个关键凭据，正是 packages/github/src/config.ts 中GitHubAppConfig接口所声明的三个字段：

export interface GitHubAppConfig { appId: string; privateKey: string; slug: string; }

• App ID：GitHub App 的数字标识，在 App 设置页"About"区域可见。
• Private Key：生成 App 时由 GitHub 签发的 PEM 私钥文件内容（需为 PKCS#8 格式，详见下文第四节）。
• Slug（App 名称标识）：App 的 URL 名称，用于拼接安装链接，形如https://github.com/apps/<slug>/installations/new（见 packages/github/src/installation.ts）。

三、环境变量配置：三个必填项

README 明确要求设置以下三个环境变量：

这三个变量在源码层面有严格的强校验逻辑。查看 packages/github/src/config.ts 的getGitHubAppConfig()：

export function getGitHubAppConfig(): GitHubAppConfig { const config = { appId: process.env.GITHUB_APP_ID, privateKey: process.env.GITHUB_APP_PRIVATE_KEY, slug: process.env.GITHUB_APP_SLUG, }; if (!validateGitHubAppConfig(config)) { throw new Error('GitHub App configuration is missing or invalid. Please check your environment variables: GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_SLUG'); } return config; }

其中validateGitHubAppConfig（config.ts）要求三个字段同时非空才算合法——任一缺失都会抛出上述明确错误提示，而不是静默降级，这保证了后续 API 调用不会因配置缺失而出现难以定位的异常。

在 Web 客户端侧，apps/web/client/src/env.ts 使用 zod 对服务端环境变量做了运行时校验声明（三者均为z.string().optional()，即对自托管场景允许缺省），并在runtimeEnv中完成从process.env的映射。这意味着若在你的部署中使用了 Onlook Web 客户端，也可以参考该文件统一管理这些变量的合法性校验。

四、私有密钥格式：为什么必须是 PKCS#8 以及如何转换

这是 README 中最容易踩坑的部分。GitHub 签发的 App 私有密钥默认可能是 PKCS#1 格式，其特征是首行标记为：

-----BEGIN RSA PRIVATE KEY-----

而@octokit/auth-app要求的则是PKCS#8格式，其首行标记为：

-----BEGIN PRIVATE KEY-----

转换命令

若拿到的是 PKCS#1 密钥，README 给出了包内置的转换命令：

bun run convert-key path/to/your-key.pem -out path/to/converted-key.pem

这条命令实际调用的是 packages/github/package.json 中定义的 npm script：

"convert-key": "openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in"

展开后等价于执行：

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in path/to/your-key.pem -out path/to/converted-key.pem

参数含义如下：

转换完成后，用转换后文件的内容（即整段 PEM 文本）填充GITHUB_APP_PRIVATE_KEY环境变量。需要留意：环境变量中的换行符应保留，建议使用支持多行值的.env文件或密钥管理服务，避免在单行 shell 内联赋值时丢失换行导致解析失败。

五、安装流程：链接生成、回调解析与 CSRF 防护

配置好环境变量后，@onlook/github提供了一整套"发起安装 → 用户授权 → 回调处理"的流程支持，核心实现在 packages/github/src/installation.ts。

5.1 生成安装链接

generateInstallationUrl()根据 App slug 拼接标准安装 URL：

const url = `https://github.com/apps/${config.slug}/installations/new?${params.toString()}`;

它支持两个可选参数（InstallationUrlOptions）：

• state：自定义状态令牌，不传时自动用uuidv4()生成，用于后续回调校验，防止 CSRF 攻击；
• redirectUrl：安装完成后 GitHub 重定向回你的服务的地址（对应redirect_uri查询参数）。

5.2 解析安装回调

用户完成安装后，GitHub 会携带installation_id、setup_action、state等查询参数重定向回你的服务。handleInstallationCallback()负责从查询字符串中提取这些字段（兼容数组形式的值），并在缺失installation_id或setup_action时返回null。

5.3 Web 端如何消费这套流程（源码证据）

在 apps/web/client/src/server/api/routers/github.ts 中可以看到两个关键封装：

• generateInstallationUrlmutation（L110-L123）：调用包的generateInstallationUrl，并且直接将当前用户 ID 作为state传入（源码注释标明"Use user ID as state for CSRF protection"）；
• handleInstallationCallbackUrlmutation（L184-L223）：首先校验回调携带的state必须与当前登录用户 ID 一致，否则抛出BAD_REQUEST；校验通过后才把installation_id写入用户的githubInstallationId字段。

回调前端页面 apps/web/client/src/app/callback/github/install/page.tsx 负责读取installation_id、setup_action、state三个参数并触发上述 mutation，随后展示"连接中/成功/失败"三种状态，成功后自动关闭新开的标签页。

六、以安装身份调用 GitHub API：createInstallationOctokit

安装成功后，业务侧需要以"某个安装"的身份访问 GitHub REST API。@onlook/github通过 packages/github/src/auth.ts 的createInstallationOctokit(installationId)完成这一能力：

export function createInstallationOctokit(installationId: string): Octokit { const config = getGitHubAppConfig(); if (!installationId || installationId.trim() === '') { throw new Error('Installation ID is required and cannot be empty.'); } return new Octokit({ authStrategy: createAppAuth, auth: { appId: config.appId, privateKey: config.privateKey, installationId: parseInt(installationId, 10), }, }); }

原理上，它借助@octokit/auth-app的createAppAuth策略：用 App 的appId+privateKey换取安装级访问令牌，从而以该安装的身份调用 API。安装 ID 为空时会显式抛出错误。

在 TRPC Router 中，getUserGitHubInstallation（routers/github.ts）从数据库读取用户的githubInstallationId，若未安装则抛出PRECONDITION_FAILED错误。基于该 Octokit 实例，Router 提供了以下业务能力：

当安装被撤销或失效时，这些过程会统一转为FORBIDDEN错误并提示"Please reinstall the GitHub App"，便于前端引导用户重新安装。

七、返回数据的类型约定

为统一各处消费的数据结构，packages/github/src/types.ts 定义了GitHubOrganization与GitHubRepository两个接口。其中GitHubRepository包含id、name、full_name、description、private、default_branch、clone_url、html_url、updated_at以及嵌套的owner（login+avatar_url）。注意 routers/github.ts 中getRepositoriesWithApp正是按该结构对 API 返回做字段映射，两者保持严格一致。

八、常见问题排查速查

以上排查项均可在 packages/github/src/config.ts、packages/github/src/auth.ts 与 apps/web/client/src/server/api/routers/github.ts 中找到对应的实现依据。只要按照"创建 GitHub App → 配置三项环境变量 → 确认密钥为 PKCS#8 → 发起安装并回调校验"的链路执行，即可在自托管部署中完整启用 Onlook 的 GitHub 集成能力。

【免费下载链接】onlookThe Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI项目地址: https://gitcode.com/GitHub_Trending/on/onlook