Connect LangSmith Engine to GitHub

Connecting GitHub lets LangSmith Engine read your source code when investigating traces and propose fixes as pull requests. A connection is optional for trace analysis.

LangSmith Cloud: Use the LangChain-managed GitHub App on GitHub.com. Start with Connect repositories.
Self-hosted LangSmith: An operator first completes Self-hosted configuration for your GitHub instance. Then, workspace users follow the same repository connection steps below.

Connect repositories

These steps apply to LangSmith Cloud and to self-hosted deployments with a configured GitHub App. Enable Engine for your tracing project or agent environment. You need permission to configure Engine in that project and to connect a GitHub integration in your LangSmith workspace. Ask a workspace administrator if those actions are unavailable. On GitHub, you need permission to install the App on the repositories you want to connect, or access to an existing installation. Your GitHub organization or enterprise may require an administrator to approve the installation. Complete your organization’s SSO sign-in when prompted.

For Enterprise Managed Users, connect organization-owned repositories. GitHub does not allow this App to be installed on a managed user’s personal account. See Enterprise Managed Users for the requirements on GitHub.com and ghe.com.

For fixes, the repository must permit Engine’s branches and draft PRs. Review Repository policies before testing a fix. To connect repositories to an existing Engine project:

Open the tracing project or agent environment. In its Engine tab, select Configure Engine.
Under Code repository, select Connect GitHub. If your workspace already has a connection, the repository picker appears instead.
In GitHub, authorize the App configured for your LangSmith deployment. Install it on the organization or account that owns your code and select the repositories it can access. If the App is already installed, LangSmith may ask you to select an existing installation.
Complete any GitHub approval prompts and return to LangSmith. Authorizing the App and installing it are separate steps: authorization identifies your GitHub account; installation grants the App access to repositories.
In the repository picker, search by account or repository name, select a repository, and click Connect repository.
Repeat for additional repositories. Each repository can have its own branch and subfolder.

You can also connect repositories while first setting up Engine, under Connect your agent’s code repository.

Choose the branch and subfolder

For each connected repository:

Branch: Select the branch Engine should read and use as the base for fixes. Leave it blank to use the repository’s default branch.
Subfolder: Optionally focus Engine on the part of the repository that contains your agent. This setting does not restrict the GitHub App’s repository access.

Engine creates fix branches in the connected repository and opens draft pull requests against the selected base branch. Review and merge those pull requests through your usual GitHub process. Engine does not merge them for you.

Connect another organization or account

One GitHub App can have an installation in each of several organizations or accounts. Repositories from those installations can be connected to the same Engine project. In the repository picker, select Install on another GitHub organization or repository…. Complete the GitHub flow, return to LangSmith, and connect the additional repositories. On self-hosted LangSmith, the App’s ownership and visibility determine which accounts GitHub offers as installation targets. On self-hosted LangSmith, all connected repositories must belong to the same GitHub instance. Connecting to a different LangSmith workspace also requires connecting the appropriate installation in that workspace.

Manage repository access

Installing an App on Only select repositories does not automatically include repositories created later. In the picker, select Missing a repo? Manage repo access for … or Manage app access →. Add the repository in GitHub, save the installation settings, and reload the picker. Removing a repository from an Engine project stops Engine from using it for that project. It does not uninstall the GitHub App or remove its access for other projects. Manage the App installation in GitHub to revoke repository access.

Verify the connection

Use a test repository and an Engine project with representative traces. On self-hosted LangSmith, ask your operator to verify webhook delivery during this test. To verify the connection:

Run an Engine analysis and confirm it can use the repository’s source code.
Generate a fix for an issue, inspect its diff, and click Open PR. Confirm that View PR opens a draft PR on the expected GitHub instance, repository, and base branch.
Review and merge the test PR. Confirm the corresponding Engine issue becomes complete.

To create PRs automatically, enable Open a draft pull request for every fix in Code repository settings.

Repository policies

Repositories must support draft PRs and allow Engine to push fix branches. Engine does not use a fork-based contribution workflow. Engine’s Git commits are unsigned. Rules that require signed commits on the fix branch can reject pushes. Branch-name rules, push restrictions, and GHES pre-receive hooks can also reject a fix. In LangSmith v0.17, fix branches use the issues-agent/ prefix. Review policies that apply to these branches and the App identity. Keep your normal review and merge requirements on the target branch. A requirement on the target branch may still need to be satisfied when a person merges; configuring the App does not bypass repository policy. Engine does not fetch Git LFS file contents or initialize Git submodules.

Troubleshoot repository selection

Symptom	What to check
GitHub is not configured, or the connection fails before GitHub opens	On self-hosted LangSmith, ask your operator to check the deployment configuration.
Your organization is not an installation target	Confirm your GitHub role, organization approval policy, and the App’s visibility. A private App can only be installed on its owning account.
Your managed-user account is not an installation target	Use an organization-owned repository. Personal managed-user repositories cannot use this integration.
The App is installed, but LangSmith has no connection	Start Connect GitHub in LangSmith, including after an administrator approves installation or you install directly from GitHub. On self-hosted LangSmith, ask your operator to check setup if authorization does not finish.
An installation or repository is missing	Check which GitHub account you authorized, the App’s selected repositories, and whether the installation was connected to this LangSmith workspace. Complete your organization’s SSO authorization when prompted.
Authorization succeeds, but the repository cannot be read	Check the App’s repository access. On self-hosted LangSmith, also ask your operator to check GitHub API and sandbox network access. Browser sign-in does not test those connections.
A fix cannot be pushed	Check rules that apply to the new fix branch, including signed-commit requirements, branch restrictions, and pre-receive hooks. See Repository policies.

Self-hosted configuration

An operator registers a GitHub App, configures LangSmith, and verifies the connection. Complete this setup once per LangSmith installation. Workspace users then connect repositories with that App. This configuration is separate from GitHub setup for LangSmith Deployments builds and previews. Use the LangSmith application images supplied with your Helm chart release.

Before you start

You need:

Engine and Sandboxes: A working self-hosted Engine deployment and permission to update its Helm values, secrets, and workloads.
GitHub administration: Permission to register and install an App on the target repositories. Enterprise or organization policies may require approval.
Network access: Browser, service, and sandbox connectivity, plus a webhook route reachable from GitHub. See Allow network access.

Choose your GitHub environment

Configure one GitHub instance and one App per LangSmith installation. Set ENGINE_GITHUB_WEB_BASE_URL to your GitHub instance’s web address:

GitHub environment	Example web address
GitHub.com, including Enterprise Cloud	`https://github.com`
Enterprise Cloud with data residency	`https://example.ghe.com`
GitHub Enterprise Server (GHES)	`https://<ghes-hostname>`

Replace the example enterprise address or GHES hostname placeholder with your own. GHES uses the same configuration on cloud infrastructure and on premises. Use HTTPS on port 443 and a fully qualified hostname, without a path such as /api/v3 or an organization name. LangSmith determines the API endpoints automatically. SSH Git URLs and custom GitHub ports are not supported.

Allow network access

All connections use HTTPS. Configure DNS, routing, and certificate trust for each source:

Source	Destination	Purpose
User’s browser	GitHub web host and LangSmith authorization callback URL	Sign-in, App authorization, and installation.
LangSmith services and Engine workers	GitHub web and API hosts	Authorization, repository information, branch and diff operations, PR creation/status, and App identity.
Sandbox hosts	GitHub web host	Clone repositories and push fix branches.
GitHub	LangSmith webhook URL	Link PRs to issues and complete issues after a merge.

For API access, allow the host for your GitHub environment:

GitHub.com: api.github.com.
Enterprise Cloud with data residency: api.example.ghe.com for a web address of https://example.ghe.com.
GHES: The same host as the web address, <ghes-hostname>.

GitHub.com and ghe.com send webhooks from outside your network; GHES sends them from your GHES environment. The webhook URL must be reachable from that source. Browser access through a VPN does not establish webhook access. For GitHub IP allow lists, include the outbound addresses of LangSmith services and sandbox hosts, including any NAT gateway addresses. Sandbox Git traffic requires direct routing to GitHub. Mandatory upstream HTTP/HTTPS forward proxies are not supported; HTTPS_PROXY on LangSmith API pods does not configure sandbox Git access. For private IP addresses or a private CA, include the private-GHES settings when configuring LangSmith below.

Register a GitHub App

Register the App on the GitHub instance that hosts your repositories. An App registered on GitHub.com cannot be reused on GHES or a ghe.com enterprise. For ghe.com, sign in through your enterprise’s identity provider. Use that site throughout registration and installation; your personal GitHub.com account and its Apps are separate.

Choose who owns the App

The App’s owner manages its registration and credentials. An installation grants access to selected repositories in an organization or account. Choose ownership and visibility based on the repositories Engine needs:

Repositories to connect	App configuration
Repositories in one organization	Create the App in that organization. Select Only on this account if it does not need installations elsewhere.
Repositories in several organizations within an enterprise	Create an enterprise-owned App and install it in each organization. This keeps installation limited to the enterprise.
Repositories in multiple organizations, or a mix of organizations and personal accounts, without managed users	Create an organization-owned App with Any account, then install it in each target account. On GHES, Any account applies only within that server.
Repositories owned by one personal account, without managed users	Create the App in the personal account and select Only on this account.

Public visibility allows other accounts to install the App. It does not make repositories public or grant access without installation. Enterprise-owned Apps have internal visibility and cannot be installed on personal accounts. Install in each organization; an enterprise-account installation does not grant repository access.

Enterprise visibility and managed users

Only enterprise members can authorize an enterprise-owned App. If outside collaborators need to connect repositories, review their enterprise access before choosing that ownership type. See GitHub’s App visibility rules or the GHES equivalent, selecting your server’s documentation version.GitHub Enterprise Cloud with data residency uses Enterprise Managed Users (EMU). Enterprise Cloud on GitHub.com can also use EMU; SSO alone does not mean an enterprise uses EMU.For EMU, connect organization-owned repositories. A managed user can register an App, but this Engine App cannot be installed on a managed user’s personal account. See GitHub’s managed-user restrictions.In an EMU enterprise, GitHub can show This enterprise instead of Any account. Only on this account limits an organization-owned App to that organization. Each target organization needs its own installation.An organization owner can install the App. Repository administrators in an EMU enterprise can install it only when it requests no organization permissions and enterprise policy permits installation.

Open the registration form

Choose the tab for the account that owns the App. These paths apply on the GitHub instance selected above:

Organization
Enterprise
Personal account

You must be an organization owner or have permission to manage its Apps.To open the registration form:

Open your profile menu and select Your organizations.
Next to the organization that should own the App, select Settings.
Open Developer settings > GitHub Apps > New GitHub App.

Complete the registration form

Use these settings for all GitHub environments and App owners. For field definitions, see Register a GitHub App. Replace https://langsmith.example.com with the browser-facing URL of your LangSmith deployment. GitHub labels the authorization callback field Callback URL or Redirect URI. Both names refer to the URL where GitHub returns users after authorization. If LangSmith uses a base path, include it. For example, a deployment at https://langsmith.example.com/langsmith uses https://langsmith.example.com/langsmith/api-host/v1/integrations/forge/github/callback as its authorization callback URL.

GitHub setting	Value
GitHub App name	A unique name for your deployment, such as `acme-langsmith-engine`.
Homepage URL	Your LangSmith URL, such as `https://langsmith.example.com`.
Callback URL / Redirect URI	`https://langsmith.example.com/api-host/v1/integrations/forge/github/callback`
Allow wildcard matching	Leave disabled, if shown.
Request user authorization (OAuth) during installation	Enabled. Engine needs the authorization callback to finish connecting an installation.
Expire user authorization tokens	Leave enabled, if shown.
Enable Device Flow	Leave disabled.
Setup URL	Leave unset. When OAuth during installation is enabled, GitHub uses the authorization callback URL and may disable this field.
Redirect on update	Enabled. Returns users to LangSmith after they update an installation.
Webhook: Active	Enabled.
Webhook URL	`https://langsmith.example.com/api-host/v1/integrations/forge/github/webhook`
Webhook secret	A separately generated random secret, also configured in LangSmith.
SSL verification	Enabled.
Where can this GitHub App be installed?	The visibility selected in Choose who owns the App. This field does not appear for enterprise-owned Apps.

For an existing App, manage token expiration under Optional Features > User-to-server token expiration. See GitHub’s token expiration settings. Generate the webhook secret with a cryptographically secure generator or your secret manager, using at least 32 random bytes. Save it for the LangSmith configuration. Under Permissions > Repository permissions, configure:

Permission	Access	Purpose
Contents	Read and write	Read code and push Engine’s fix branches.
Pull requests	Read and write	Create draft PRs and read their status.
Metadata	Read-only, selected automatically	Identify repositories.

Leave organization, account, and enterprise permissions unset. Engine’s standard investigation and fix workflow does not require administration, workflow, or Checks permissions. Under Subscribe to events, select Pull request. These events let Engine link externally created PRs that include Engine’s issue reference and mark issues complete after a merge. Select Create GitHub App.

Save the App values

After creating the App, open its settings and prepare the credentials:

Under Client secrets, select Generate a new client secret and save it immediately.
Under Private keys, select Generate a private key. Keep the downloaded PEM file; LangSmith needs its complete contents, including newlines.
Generate a separate OAuth state secret of at least 32 random bytes with your secret manager or a cryptographically secure generator. Use it only in LangSmith; do not enter it into GitHub or reuse the webhook secret.

Use this mapping when configuring LangSmith:

Value	LangSmith environment variable
GitHub instance’s web address	`ENGINE_GITHUB_WEB_BASE_URL`
App ID (numeric)	`ENGINE_GITHUB_APP_ID`
Public link (full URL)	`ENGINE_GITHUB_APP_PUBLIC_LINK`
Client ID	`ENGINE_GITHUB_APP_CLIENT_ID`
Client secret	`ENGINE_GITHUB_APP_CLIENT_SECRET`
Private key (PEM contents)	`ENGINE_GITHUB_APP_PRIVATE_KEY`
Callback URL / Redirect URI	`ENGINE_GITHUB_OAUTH_REDIRECT_URI`
Webhook secret	`ENGINE_GITHUB_APP_WEBHOOK_SECRET`
OAuth state secret	`ENGINE_GITHUB_OAUTH_STATE_SECRET`

Copy the numeric App ID, not the Client ID or installation ID. Copy Public link exactly, including its full path; do not use the developer settings URL or an installation URL ending in /installations/new. Use the exact authorization callback URL and webhook secret entered in GitHub. Include any LangSmith base path in the callback URL. The GitHub web address is the one selected in Choose your GitHub environment.

Configure LangSmith

Store credentials

Using your existing secret-management workflow, create a Kubernetes Secret in the LangSmith namespace for the Client secret, private key, webhook secret, and OAuth state secret. The Helm example references a Secret named langsmith-engine-github. You can choose a different Secret name and keys; update the secretKeyRef entries to match. Store credentials in Secrets, not in committed Helm values or command-line arguments. App IDs, Client IDs, and URLs can be included in Helm values.

Set Helm values

Enable hostBackend and place all ENGINE_GITHUB_* settings in commonEnv. Merge the following with your existing Helm values, preserving unrelated entries. Replace the placeholders and example URLs:

commonEnv:
  - name: ENGINE_GITHUB_WEB_BASE_URL
    value: "https://<ghes-hostname>"
  - name: ENGINE_GITHUB_APP_ID
    value: "<app-id>"
  - name: ENGINE_GITHUB_APP_PUBLIC_LINK
    value: "<public-link-copied-from-github>"
  - name: ENGINE_GITHUB_APP_CLIENT_ID
    value: "<client-id>"
  - name: ENGINE_GITHUB_OAUTH_REDIRECT_URI
    value: "https://langsmith.example.com/api-host/v1/integrations/forge/github/callback"
  - name: ENGINE_GITHUB_APP_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: langsmith-engine-github
        key: client_secret
  - name: ENGINE_GITHUB_APP_PRIVATE_KEY
    valueFrom:
      secretKeyRef:
        name: langsmith-engine-github
        key: private_key
  - name: ENGINE_GITHUB_OAUTH_STATE_SECRET
    valueFrom:
      secretKeyRef:
        name: langsmith-engine-github
        key: oauth_state_secret
  - name: ENGINE_GITHUB_APP_WEBHOOK_SECRET
    valueFrom:
      secretKeyRef:
        name: langsmith-engine-github
        key: webhook_secret

hostBackend:
  enabled: true

Remove these variables from component-specific extraEnv lists, including hostBackend.deployment.extraEnv, to avoid duplicate definitions. The shared configuration supplies the same values to API and background workloads. The chart’s config.hostname, config.frontendHostname if used, and config.basePath must also describe the URL users open in their browser.

Private GHES deployments

If GHES uses private IP addresses or a private CA, include the applicable settings below before applying the values file. GHES on a private network For a GHES hostname that resolves to private IP addresses, configure private DNS and network routing from LangSmith and the sandbox hosts. Also set the following environment variables through the listed Helm values:

Helm environment list	Variable	Value
`platformBackend.deployment.extraEnv`	`SSRF_ALLOW_PRIVATE_IPS_ENGINE`	`"true"`
`ingestQueue.deployment.extraEnv`	`SSRF_ALLOW_PRIVATE_IPS_ENGINE`	`"true"`
`sandboxes.sandboxHost.deployment.extraEnv`	`SSRF_ALLOW_PRIVATE_IPS_EGRESS`	`"true"`

These settings allow the respective components to reach private addresses; they do not create DNS records or network routes. They affect more than this GitHub hostname. Retain network restrictions for the destinations your deployment actually needs, and keep protections for metadata, loopback, and Kubernetes-internal addresses enabled. GHES with a private certificate authority LangSmith services and sandbox hosts must trust the CA that signed your GHES certificate. Configuring trust only in your browser or inside a sandbox is insufficient. Follow Mount internal CAs for TLS to configure config.customCa.secretName and config.customCa.secretKey. Include your private CA and any public roots needed for other outbound connections in the bundle. Also set REQUESTS_CA_BUNDLE in hostBackend.deployment.extraEnv to /etc/ssl/certs/custom-ca-certificates.crt, the path where the chart mounts that bundle. This setting is required for the GitHub integration in addition to the chart’s TLS configuration. Check that the bundle reaches the GitHub integration, platform API and workers, Engine execution workers, and sandbox hosts. Keep TLS verification enabled. The sandbox proxy’s own CA is separate from the CA used to verify GHES.

Apply the configuration

Apply the complete values file through your normal deployment process, using a matching LangSmith image and chart release. For Helm upgrades, see Upgrade a self-hosted deployment. Wait for the affected API and worker rollouts to finish before connecting repositories. Updating a Secret in place does not reload environment variables in running containers; restart affected workloads after credential changes.

Verify webhook delivery

After the rollout, connect a test repository and verify the connection. While creating and merging the test PR, check the App’s webhook deliveries:

In the GitHub App’s settings, open Advanced > Recent deliveries.
Confirm that pull_request deliveries reach LangSmith successfully. LangSmith returns HTTP 202 when it accepts a valid signed delivery.

A successful webhook response alone does not prove the event matched an Engine issue. Complete the merge check in Verify the connection.

Troubleshoot setup

Symptom	What to check
GitHub is not configured	Confirm the App ID, Client ID, Client secret, private key, state secret, and App’s public link are set. Check the GitHub URL format and complete the rollout. This notice identifies missing configuration; it does not test whether credentials are valid.
GitHub is temporarily unavailable after authorization	Confirm that the Client secret and private key belong to the configured App ID and Client ID. Check GitHub connectivity and certificate trust, then restart Connect GitHub.
GitHub authorization opens on the wrong instance	Check `ENGINE_GITHUB_WEB_BASE_URL` in shared configuration and remove conflicting component overrides.
The callback returns HTML or 404	Check the `/api-host` route, LangSmith base path, and exact authorization callback URL.
Installation does not return to LangSmith	Enable Request user authorization (OAuth) during installation. Check the exact authorization callback URL and confirm the Client ID and Client secret belong to this App. Then restart Connect GitHub in LangSmith.
Repositories appear, but cloning or pushing fails	Check sandbox-host DNS, routing, private-IP settings, certificate trust, and GitHub IP/push policies.
PR creation fails after a successful push	Check Pull requests: Read and write, draft PR availability, and the selected base branch.
A merge does not complete an issue	Check Pull request event subscription, webhook reachability, the matching webhook secret, and Recent deliveries. Redeliver failed events after correcting the cause.

If GitHub cannot deliver webhooks, repository reads, fixes, and PR creation can still work. Webhook-driven PR linking and automatic issue completion after merges do not work. Restore delivery and redeliver missed events from GitHub’s App settings. For PRs created with an external coding assistant, preserve the issue reference from Copy Fix Context in the PR description. This reference lets Engine link the PR to the issue. For missing organizations or repositories, see Troubleshoot repository selection. When asking for help, include your LangSmith and Helm chart versions, GitHub environment and GHES version if applicable, App ownership type, and the step that fails. Do not include private keys, client secrets, webhook secrets, or access tokens.

Change or rotate configuration

For a private-key rotation, add the new key in GitHub, update the deployment Secret, and restart affected workloads. Validate the connection before removing the old key. Follow the same overlap approach where GitHub supports multiple client secrets. For webhook-secret rotation, coordinate the GitHub and LangSmith values. Deliveries during a mismatch fail signature verification. Review Recent deliveries and redeliver failed events after both sides use the new secret. Replacing the App requires installing the replacement and reconnecting affected LangSmith workspaces. Plan for an interruption until repository access is restored. Transferring App ownership can also change where it can be installed and its public link; review GitHub’s transfer behavior before making the change. Do not change ENGINE_GITHUB_WEB_BASE_URL on an existing connected deployment as a migration procedure. Changing the URL does not migrate repository connections or existing PR references. Plan a migration with LangChain support before switching GitHub instances.

​Connect repositories

​Choose the branch and subfolder

​Connect another organization or account

​Manage repository access

​Verify the connection

​Repository policies

​Troubleshoot repository selection

​Self-hosted configuration

​Before you start

​Choose your GitHub environment

​Allow network access

​Register a GitHub App

​Choose who owns the App

​Open the registration form

​Complete the registration form

​Save the App values

​Configure LangSmith

​Store credentials

​Set Helm values

​Private GHES deployments

​Apply the configuration

​Verify webhook delivery

​Troubleshoot setup

​Change or rotate configuration

​See also

Connect repositories

Choose the branch and subfolder

Connect another organization or account

Manage repository access

Verify the connection

Repository policies

Troubleshoot repository selection

Self-hosted configuration

Before you start

Choose your GitHub environment

Allow network access

Register a GitHub App

Choose who owns the App

Open the registration form

Complete the registration form

Save the App values

Configure LangSmith

Store credentials

Set Helm values

Private GHES deployments

Apply the configuration

Verify webhook delivery

Troubleshoot setup

Change or rotate configuration

See also