> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-docsby-1791319236-3be7a15.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect LangSmith Engine to GitHub

> Connect GitHub repositories to Engine, or configure a GitHub App for self-hosted LangSmith using GitHub.com, Enterprise Cloud with data residency, or Enterprise Server.

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](#connect-repositories).
* **Self-hosted LangSmith**: An operator first completes [Self-hosted configuration](#self-hosted-configuration) for your GitHub instance. Then, workspace users follow the same repository connection steps below.

<a id="langsmith-cloud" />

## Connect repositories

These steps apply to LangSmith Cloud and to self-hosted deployments with a configured GitHub App.

Enable [Engine](/langsmith/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.

<Note>
  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](#enterprise-managed-users) for the requirements on GitHub.com and `ghe.com`.
</Note>

For fixes, the repository must permit Engine's branches and draft PRs. Review [Repository policies](#repository-policies) before testing a fix.

To connect repositories to an existing Engine project:

1. Open the tracing project or agent environment. In its **Engine** tab, select **Configure Engine**.
2. Under **Code repository**, select **Connect GitHub**. If your workspace already has a connection, the repository picker appears instead.
3. 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.
4. 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.
5. In the repository picker, search by account or repository name, select a repository, and click **Connect repository**.
6. 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](#choose-who-owns-the-app) 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](#verify-webhook-delivery) during this test.

To verify the connection:

1. Run an Engine analysis and confirm it can use the repository's source code.
2. 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.
3. 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](#configure-langsmith). |
| 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](#troubleshoot-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](#allow-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](#repository-policies). |

<a id="self-hosted" />

## 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](#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](/langsmith/engine-self-hosted) 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](#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](#private-ghes-deployments) when configuring LangSmith below.

<a id="create-a-github-app" />

### 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.

<Accordion title="Enterprise visibility and managed users" id="enterprise-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](https://docs.github.com/en/enterprise-cloud@latest/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private) or the [GHES equivalent](https://docs.github.com/en/enterprise-server@3.20/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private), selecting your server's documentation version.

  [GitHub Enterprise Cloud with data residency](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/about-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](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts#github-apps).

  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.
</Accordion>

#### Open the registration form

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

<Tabs>
  <Tab title="Organization">
    You must be an organization owner or have permission to manage its Apps.

    To open the registration form:

    1. Open your profile menu and select **Your organizations**.
    2. Next to the organization that should own the App, select **Settings**.
    3. Open **Developer settings** > **GitHub Apps** > **New GitHub App**.
  </Tab>

  <Tab title="Enterprise">
    An enterprise owner completes these steps. On GHES, enterprise-owned Apps require version 3.17 or later. On older versions, use an organization-owned App with the visibility needed for your repositories.

    To open the registration form:

    1. Open your profile menu. With managed users, select **Your enterprise**. With personal accounts, select **Your enterprises**, then open the enterprise's **Settings**.
    2. In the enterprise sidebar, under **Settings**, select **GitHub Apps**.
    3. Select **New GitHub App**.

    For GitHub's instructions, see [Create an App for your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-github-apps-for-your-enterprise/creating-github-apps-for-your-enterprise).
  </Tab>

  <Tab title="Personal account">
    Use this option for a personal account without managed users.

    Open your profile menu and select **Settings** > **Developer settings** > **GitHub Apps** > **New GitHub App**.
  </Tab>
</Tabs>

#### Complete the registration form

Use these settings for all GitHub environments and App owners. For field definitions, see [Register a GitHub App](https://docs.github.com/en/enterprise-cloud@latest/apps/creating-github-apps/registering-a-github-app/registering-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](#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](https://docs.github.com/en/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens#configuring-your-app-to-use-user-access-tokens-that-expire).

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:

1. Under **Client secrets**, select **Generate a new client secret** and save it immediately.
2. Under **Private keys**, select **Generate a private key**. Keep the downloaded PEM file; LangSmith needs its complete contents, including newlines.
3. 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](#choose-your-github-environment).

### Configure LangSmith

#### Store credentials

Using your [existing secret-management workflow](/langsmith/self-host-using-an-existing-secret), 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.

<a id="enable-the-github-integration-routes" />

#### 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:

```yaml theme={null}
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.

<a id="ghes-on-a-private-network" />

**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.

<a id="ghes-with-a-private-certificate-authority" />

**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](/langsmith/self-host-custom-tls-certificates#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](/langsmith/self-host-upgrades).

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.

<a id="verify-the-integration" />

### Verify webhook delivery

After the rollout, [connect a test repository and verify the connection](#verify-the-connection). While creating and merging the test PR, check the App's webhook deliveries:

1. In the GitHub App's settings, open **Advanced** > **Recent deliveries**.
2. 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](#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](#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.

## See also

* [Find and fix your agent's issues](/langsmith/engine)
* [Engine on self-hosted LangSmith](/langsmith/engine-self-hosted)
* [Engine security](/langsmith/engine-security)
* [Configure self-hosted environment variables](/langsmith/self-host-environment-variables)

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/engine-github.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>