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/src/config.ts读取并校验 GitHub App 三项环境变量配置packages/github/src/auth.ts基于安装 ID 创建已鉴权的 Octokit 实例packages/github/src/installation.ts生成 GitHub App 安装链接并解析安装回调参数packages/github/src/types.ts定义组织与仓库的数据结构类型从 packages/github/package.json 的依赖声明可以看到该包围绕 Octokit 生态构建octokit/auth-appApp 级鉴权策略、octokit/restGitHub 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 IDGitHub App 的数字标识在 App 设置页About区域可见。Private Key生成 App 时由 GitHub 签发的 PEM 私钥文件内容需为 PKCS#8 格式详见下文第四节。SlugApp 名称标识App 的 URL 名称用于拼接安装链接形如https://github.com/apps/slug/installations/new见 packages/github/src/installation.ts。三、环境变量配置三个必填项README 明确要求设置以下三个环境变量环境变量含义是否必填GITHUB_APP_IDGitHub App 的 ID必填GITHUB_APP_PRIVATE_KEYGitHub App 的私有密钥PKCS#8 格式必填GITHUB_APP_SLUGGitHub App 的 slug 名称必填这三个变量在源码层面有严格的强校验逻辑。查看 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; }其中validateGitHubAppConfigconfig.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 scriptconvert-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参数含义如下参数作用pkcs8 -topk8将任意 PEM 私钥转换为 PKCS#8 格式-inform PEM声明输入为 PEM 编码-outform PEM指定输出仍为 PEM 编码-nocrypt输出密钥不加密便于直接以文本形式放入环境变量-in/-out指定输入、输出文件路径转换完成后用转换后文件的内容即整段 PEM 文本填充GITHUB_APP_PRIVATE_KEY环境变量。需要留意环境变量中的换行符应保留建议使用支持多行值的.env文件或密钥管理服务避免在单行 shell 内联赋值时丢失换行导致解析失败。五、安装流程链接生成、回调解析与 CSRF 防护配置好环境变量后onlook/github提供了一整套发起安装 → 用户授权 → 回调处理的流程支持核心实现在 packages/github/src/installation.ts。5.1 生成安装链接generateInstallationUrl()根据 App slug 拼接标准安装 URLconst url https://github.com/apps/${config.slug}/installations/new?${params.toString()};它支持两个可选参数InstallationUrlOptionsstate自定义状态令牌不传时自动用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 中可以看到两个关键封装generateInstallationUrlmutationL110-L123调用包的generateInstallationUrl并且直接将当前用户 ID 作为state传入源码注释标明Use user ID as state for CSRF protectionhandleInstallationCallbackUrlmutationL184-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 APIcreateInstallationOctokit安装成功后业务侧需要以某个安装的身份访问 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 的appIdprivateKey换取安装级访问令牌从而以该安装的身份调用 API。安装 ID 为空时会显式抛出错误。在 TRPC Router 中getUserGitHubInstallationrouters/github.ts从数据库读取用户的githubInstallationId若未安装则抛出PRECONDITION_FAILED错误。基于该 Octokit 实例Router 提供了以下业务能力TRPC 过程底层 API 调用用途validateoctokit.rest.repos.get校验仓库存在性返回默认分支与是否为私有仓库getRepooctokit.rest.repos.get获取仓库详情getOrganizationsoctokit.rest.apps.getInstallation判断安装对象是否为组织返回组织信息getRepoFilesoctokit.rest.repos.getContent按路径支持分支/Tag/SHA 的ref读取仓库文件checkGitHubAppInstallationoctokit.rest.apps.getInstallation探测安装是否仍有效getRepositoriesWithAppoctokit.rest.apps.listReposAccessibleToInstallation列出安装可访问的仓库每页 100 条经转换后返回当安装被撤销或失效时这些过程会统一转为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以及嵌套的ownerloginavatar_url。注意 routers/github.ts 中getRepositoriesWithApp正是按该结构对 API 返回做字段映射两者保持严格一致。八、常见问题排查速查现象可能原因处理方式启动即报GitHub App configuration is missing or invalid...三个环境变量未全部设置核对GITHUB_APP_ID/GITHUB_APP_PRIVATE_KEY/GITHUB_APP_SLUG是否均非空鉴权失败、REST 调用返回密钥相关错误私钥为 PKCS#1 格式按第四节执行bun run convert-key转换为 PKCS#8 后重试业务调用抛FORBIDDEN提示安装无效或已被撤销安装被用户删除、App 权限变更引导用户重新走安装流程重新生成安装链接回调报Invalid state parameterstate与当前用户 ID 不匹配确认回调state未被篡改或过期重新发起安装PRECONDITION_FAILEDGitHub App installation required用户尚未完成安装先调用generateInstallationUrl引导安装以上排查项均可在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/src/config.ts读取并校验 GitHub App 三项环境变量配置packages/github/src/auth.ts基于安装 ID 创建已鉴权的 Octokit 实例packages/github/src/installation.ts生成 GitHub App 安装链接并解析安装回调参数packages/github/src/types.ts定义组织与仓库的数据结构类型从 packages/github/package.json 的依赖声明可以看到该包围绕 Octokit 生态构建octokit/auth-appApp 级鉴权策略、octokit/restGitHub 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 IDGitHub App 的数字标识在 App 设置页About区域可见。Private Key生成 App 时由 GitHub 签发的 PEM 私钥文件内容需为 PKCS#8 格式详见下文第四节。SlugApp 名称标识App 的 URL 名称用于拼接安装链接形如https://github.com/apps/slug/installations/new见 packages/github/src/installation.ts。三、环境变量配置三个必填项README 明确要求设置以下三个环境变量环境变量含义是否必填GITHUB_APP_IDGitHub App 的 ID必填GITHUB_APP_PRIVATE_KEYGitHub App 的私有密钥PKCS#8 格式必填GITHUB_APP_SLUGGitHub App 的 slug 名称必填这三个变量在源码层面有严格的强校验逻辑。查看 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; }其中validateGitHubAppConfigconfig.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 scriptconvert-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参数含义如下参数作用pkcs8 -topk8将任意 PEM 私钥转换为 PKCS#8 格式-inform PEM声明输入为 PEM 编码-outform PEM指定输出仍为 PEM 编码-nocrypt输出密钥不加密便于直接以文本形式放入环境变量-in/-out指定输入、输出文件路径转换完成后用转换后文件的内容即整段 PEM 文本填充GITHUB_APP_PRIVATE_KEY环境变量。需要留意环境变量中的换行符应保留建议使用支持多行值的.env文件或密钥管理服务避免在单行 shell 内联赋值时丢失换行导致解析失败。五、安装流程链接生成、回调解析与 CSRF 防护配置好环境变量后onlook/github提供了一整套发起安装 → 用户授权 → 回调处理的流程支持核心实现在 packages/github/src/installation.ts。5.1 生成安装链接generateInstallationUrl()根据 App slug 拼接标准安装 URLconst url https://github.com/apps/${config.slug}/installations/new?${params.toString()};它支持两个可选参数InstallationUrlOptionsstate自定义状态令牌不传时自动用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 中可以看到两个关键封装generateInstallationUrlmutationL110-L123调用包的generateInstallationUrl并且直接将当前用户 ID 作为state传入源码注释标明Use user ID as state for CSRF protectionhandleInstallationCallbackUrlmutationL184-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 APIcreateInstallationOctokit安装成功后业务侧需要以某个安装的身份访问 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 的appIdprivateKey换取安装级访问令牌从而以该安装的身份调用 API。安装 ID 为空时会显式抛出错误。在 TRPC Router 中getUserGitHubInstallationrouters/github.ts从数据库读取用户的githubInstallationId若未安装则抛出PRECONDITION_FAILED错误。基于该 Octokit 实例Router 提供了以下业务能力TRPC 过程底层 API 调用用途validateoctokit.rest.repos.get校验仓库存在性返回默认分支与是否为私有仓库getRepooctokit.rest.repos.get获取仓库详情getOrganizationsoctokit.rest.apps.getInstallation判断安装对象是否为组织返回组织信息getRepoFilesoctokit.rest.repos.getContent按路径支持分支/Tag/SHA 的ref读取仓库文件checkGitHubAppInstallationoctokit.rest.apps.getInstallation探测安装是否仍有效getRepositoriesWithAppoctokit.rest.apps.listReposAccessibleToInstallation列出安装可访问的仓库每页 100 条经转换后返回当安装被撤销或失效时这些过程会统一转为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以及嵌套的ownerloginavatar_url。注意 routers/github.ts 中getRepositoriesWithApp正是按该结构对 API 返回做字段映射两者保持严格一致。八、常见问题排查速查现象可能原因处理方式启动即报GitHub App configuration is missing or invalid...三个环境变量未全部设置核对GITHUB_APP_ID/GITHUB_APP_PRIVATE_KEY/GITHUB_APP_SLUG是否均非空鉴权失败、REST 调用返回密钥相关错误私钥为 PKCS#1 格式按第四节执行bun run convert-key转换为 PKCS#8 后重试业务调用抛FORBIDDEN提示安装无效或已被撤销安装被用户删除、App 权限变更引导用户重新走安装流程重新生成安装链接回调报Invalid state parameterstate与当前用户 ID 不匹配确认回调state未被篡改或过期重新发起安装PRECONDITION_FAILEDGitHub App installation required用户尚未完成安装先调用generateInstallationUrl引导安装以上排查项均可在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考