将 LangSmith Engine 连接到 GitHub

在 LangSmith Cloud 中将 LangSmith Engine 连接到 GitHub，或为自托管部署创建并配置你自己的 GitHub App。

连接 GitHub 仓库是可选的。连接后，LangSmith Engine 会读取源代码以诊断问题，并打开包含建议修复的 pull request。在 LangSmith Cloud 中，Engine 使用由 LangChain 管理的 GitHub App；自托管运维人员则创建并管理自己的 GitHub App。

LangSmith Cloud

在 LangSmith Cloud 中，Engine 通过由 LangChain 管理的 GitHub App 进行连接。你无需自行创建或配置 App。

要连接你的仓库：

1. 在 LangSmith 控制台中，打开一个追踪项目并转到 Engine 选项卡。
2. 在 Connect your agent's code repository 下，点击 Connect GitHub 并授权 LangChain 管理的 GitHub App。
3. 在 Engine 应访问的仓库上安装该 App。在 GitHub 组织上安装 App 可能需要 GitHub 组织所有者的批准。如果你不是所有者，GitHub 会向所有者发送安装请求，待其批准后 App 才可用。
4. 在 Engine 选项卡的 GitHub Repository 字段中选择已连接的仓库。

有关托管 App 的访问和保留模型，请参阅 Engine 安全。

自托管

NOTE

Engine 仅连接到 github.com。不支持 GitHub Enterprise Server：Engine 的沙箱会访问 github.com 和 api.github.com，而沙箱身份验证代理仅为这些主机注入仓库凭据。无法使用在 GitHub Enterprise Server 实例上创建的 GitHub App。

要为自托管部署创建并配置 GitHub App：

创建 GitHub App

Create the app

转到 GitHub Settings > Developer settings > GitHub Apps 并点击 New GitHub App。

• GitHub App name：任意唯一名称，例如 acme-langsmith-engine。
• Homepage URL：你的 LangSmith 部署 URL，例如 https://langsmith.example.com。
• Where can this GitHub App be installed?：对于大多数自托管部署，选择 Only on this account。仅当你打算分发该 App 时才选择 Any account。

Set the callback URL

添加以下 Callback URL，将 <langsmith-host> 替换为你的 LangSmith 主机名：

https://<langsmith-host>/api-host/v1/integrations/forge/github/callback

Set the webhook URL and secret

使用你的密钥管理器或其他加密安全的生成器生成至少 32 字节的随机 webhook 密钥。将此值存储在你的 LangSmith 密钥存储中。

在 Webhook 下，选择 Active 并设置 Webhook URL，将 <langsmith-host> 替换为你的 LangSmith 主机名：

https://<langsmith-host>/api-host/v1/integrations/forge/github/webhook

在 Webhook secret 中输入生成的值。

Set repository permissions

在 Permissions > Repository permissions 下，授予以下权限：

• Contents：Read and write。
• Pull requests：Read and write。
• Metadata：Read-only（自动选择）。

在 Subscribe to events 下，不选择任何事件。Engine 不需要任何事件订阅。

Create the app and gather its values

点击 Create GitHub App。GitHub 会在 App 设置页面提供以下值：

值	在哪里找到	环境变量
App ID	页面顶部的数字	FORGE_GITHUB_APP_ID
Public link	例如 https://github.com/apps/acme-langsmith-engine	FORGE_GITHUB_APP_PUBLIC_LINK
Client ID	在 About 下	FORGE_GITHUB_CLIENT_ID
Client secret	在 Client secrets 下，点击 Generate a new client secret（仅显示一次）	FORGE_GITHUB_CLIENT_SECRET
Private key	在 Private keys 下，点击 Generate a private key（下载 .pem 文件）	FORGE_GITHUB_APP_PEM

Generate a state JWT secret

LangSmith 使用 HMAC 密钥对短期 OAuth state token 进行签名并保护回调 state。使用你的密钥管理器或其他加密安全的生成器生成至少 32 字节的随机密钥。GitHub 不提供此值。

这是 FORGE_GITHUB_STATE_JWT_SECRET。请单独生成，不要复用 webhook 密钥或任何其他凭据。

Create a Kubernetes Secret

WARNING

GitHub 客户端密钥、私钥、state JWT 密钥和 webhook 密钥都是凭据。只能将它们存储在 Kubernetes Secret 中，绝不能放在 Helm values 或命令行参数中。

使用你现有的密钥管理工作流，创建一个名为 langsmith-forge-github 的 Kubernetes Secret，包含以下键：

键	值
forge_github_client_secret	GitHub 客户端密钥
forge_github_state_jwt_secret	单独生成的 state JWT 密钥
forge_github_app_pem	GitHub App 私钥 PEM 的内容
forge_github_webhook_secret	同时配置在 GitHub 中的 webhook 密钥

对于生产部署，请使用你现有的密钥工作流，例如 Sealed Secrets 或 External Secrets Operator。

Add the configuration to your langsmith_config.yaml

将以下内容添加到 langsmith_config.yaml 中的 hostBackend.deployment.extraEnv。App ID、public link 和 client ID 使用字面 value 条目。通过 secretKeyRef 引用客户端密钥、state JWT 密钥、私钥和 webhook 密钥；绝不要通过 commonEnv 或内联值设置它们：

hostBackend:
  deployment:
    extraEnv:
      - name: FORGE_GITHUB_APP_ID
        value: "<app-id>"
      - name: FORGE_GITHUB_APP_PUBLIC_LINK
        value: "https://github.com/apps/<app-slug>"
      - name: FORGE_GITHUB_CLIENT_ID
        value: "<client-id>"
      - name: FORGE_GITHUB_CLIENT_SECRET
        valueFrom:
          secretKeyRef:
            name: langsmith-forge-github
            key: forge_github_client_secret
      - name: FORGE_GITHUB_STATE_JWT_SECRET
        valueFrom:
          secretKeyRef:
            name: langsmith-forge-github
            key: forge_github_state_jwt_secret
      - name: FORGE_GITHUB_APP_PEM
        valueFrom:
          secretKeyRef:
            name: langsmith-forge-github
            key: forge_github_app_pem
      - name: FORGE_GITHUB_WEBHOOK_SECRET
        valueFrom:
          secretKeyRef:
            name: langsmith-forge-github
            key: forge_github_webhook_secret

应用 Helm 配置：

helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug

Install the app on repositories

Pod 健康后，在 Engine 应访问的仓库上安装 GitHub App：

1. 打开该 App 的 public link（FORGE_GITHUB_APP_PUBLIC_LINK）并点击 Install，或在你的 GitHub 组织中打开 Settings > Applications > GitHub Apps。
2. 选择 Engine 应访问的仓库。如果安装未授予对所有仓库的访问权限，请显式选择 Engine 需要的每个私有仓库。
3. 在 LangSmith 中，打开一个追踪项目，转到 Engine 选项卡，并在 GitHub Repository 字段中选择该仓库。

连接的仓库让 Engine 可以使用你的源代码进行诊断，并打开包含建议修复的 pull request。

另请参阅

• 查找并修复 agent 的问题：Engine 设置、成本和问题工作流。
• 自托管上的 Engine：安装、架构和数据处理。
• Engine 安全：Engine 如何处理你的数据和 GitHub 访问。

---