You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(fleet): replace GitHub OAuth setup with GitHub App instructions
Fleet now integrates with GitHub via a dedicated GitHub App rather than
an OAuth app. Remove the old OAuth provider guide and add a new
"Enable GitHub App for Fleet" section covering app creation, required
permissions, callback/webhook URLs, private key / webhook secret / state
JWT generation, Kubernetes secret storage, and values.yaml wiring.
@@ -67,13 +67,16 @@ You can store the encryption key in a predefined Kubernetes secret using the `fl
67
67
68
68
## Enable OAuth tools and triggers (optional)
69
69
70
-
To enable OAuth-based tools (like Gmail, Slack, GitHub), configure the `oauthProviderOrgId` and add provider IDs for each integration you want to enable. You can enable any combination of providers.
70
+
To enable OAuth-based tools (like Gmail, Slack, Linear), configure the `oauthProviderOrgId` and add provider IDs for each integration you want to enable. You can enable any combination of providers.
71
+
72
+
<Note>
73
+
GitHub tools are no longer configured through an OAuth provider. Fleet now integrates with GitHub via a dedicated GitHub App. See [Enable GitHub App for Fleet](#enable-github-app-for-fleet) below.
To enable Google OAuth for Fleet, you need to create an OAuth client in GCP and configure it with the required URLs and credentials.
@@ -495,6 +434,183 @@ To enable Slack OAuth for Fleet, you need to create a Slack app and configure it
495
434
</Accordion>
496
435
</AccordionGroup>
497
436
437
+
## Enable GitHub App for Fleet
438
+
439
+
Fleet integrates with GitHub through a dedicated **GitHub App** (not an OAuth app). The GitHub App provides repository access for Fleet's GitHub tools and supports the user authorization flow required for private repository access.
440
+
441
+
Setup involves creating a GitHub App, gathering its credentials, storing them as Kubernetes secrets, and referencing them from `values.yaml`.
442
+
443
+
<Steps>
444
+
<Steptitle="Create a GitHub App">
445
+
Go to [GitHub Settings > Developer settings > GitHub Apps](https://github.com/settings/apps) and click **New GitHub App**.
446
+
447
+
<Note>
448
+
You can create the app under a personal account or an organization. If multiple people will manage the integration, an organization-owned app is recommended.
449
+
</Note>
450
+
</Step>
451
+
452
+
<Steptitle="Fill in basic details">
453
+
-**GitHub App name**: Any unique name, for example `acme-langsmith-fleet`. Make a note of the slug GitHub generates (the lowercased, hyphenated form of the name — this is the value you'll use for `FLEET_GITHUB_APP_SLUG`).
454
+
-**Homepage URL**: Your LangSmith hostname, for example `https://langsmith.acme.com`.
455
+
- Uncheck **Active** under **Webhook** for now — you'll enable it in a later step after generating a webhook secret.
456
+
</Step>
457
+
458
+
<Steptitle="Set callback URLs">
459
+
Under **Identifying and authorizing users**, add the following **Callback URL**, replacing `<hostname>` with your LangSmith hostname:
- Paste the generated value into **Webhook secret**. Save it — you'll need the same value when configuring LangSmith.
492
+
</Step>
493
+
494
+
<Steptitle="Set repository permissions">
495
+
Under **Permissions > Repository permissions**, grant the following:
496
+
497
+
-**Contents**: Read and write
498
+
-**Issues**: Read and write
499
+
-**Pull requests**: Read and write
500
+
-**Metadata**: Read-only (automatically selected)
501
+
502
+
Under **Permissions > Account permissions**, grant **Email addresses: Read-only**.
503
+
504
+
<Note>
505
+
These are the minimum permissions required for Fleet's built-in GitHub tools (issue management, pull request creation, repository content access). Adjust if you need additional tool capabilities.
506
+
</Note>
507
+
</Step>
508
+
509
+
<Steptitle="Choose install visibility">
510
+
Under **Where can this GitHub App be installed?**, select whichever option matches your distribution needs. For most self-hosted deployments, **Only on this account** is correct.
511
+
</Step>
512
+
513
+
<Steptitle="Create the app">
514
+
Click **Create GitHub App**. You'll be taken to the app's settings page, where several values are now available:
515
+
516
+
-**App ID** (numeric, at the top of the page) → `FLEET_GITHUB_APP_ID`
517
+
-**Public link** (for example, `https://github.com/apps/acme-langsmith-fleet`) → `FLEET_GITHUB_APP_PUBLIC_LINK`
518
+
- App slug (the last path segment of the public link) → `FLEET_GITHUB_APP_SLUG`
Under **Client secrets**, click **Generate a new client secret** and copy the value. This is `FLEET_GITHUB_APP_CLIENT_SECRET`. GitHub only shows it once.
524
+
</Step>
525
+
526
+
<Steptitle="Generate a private key">
527
+
Scroll to **Private keys** and click **Generate a private key**. GitHub will download a `.pem` file. Keep this file secure — it grants full access to the GitHub App. The PEM contents are `FLEET_GITHUB_APP_PRIVATE_KEY`.
528
+
</Step>
529
+
530
+
<Steptitle="Generate a state JWT secret">
531
+
The backend signs short-lived OAuth state tokens with an HMAC key. Generate one:
For production deployments, we recommend managing this secret through your existing secrets workflow (for example, [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) or [External Secrets Operator](https://external-secrets.io/)). See [Use an existing secret](/langsmith/self-host-using-an-existing-secret) for more on managing LangSmith secrets.
553
+
</Step>
554
+
555
+
<Steptitle="Configure values.yaml">
556
+
Add the following to your `values.yaml`, replacing the placeholder values with the non-sensitive values gathered above:
557
+
558
+
```yaml
559
+
commonEnv:
560
+
- name: FLEET_GITHUB_APP_ID
561
+
value: "<app-id>"
562
+
- name: FLEET_GITHUB_APP_SLUG
563
+
value: "<app-slug>"
564
+
- name: FLEET_GITHUB_APP_PUBLIC_LINK
565
+
value: "https://github.com/apps/<app-slug>"
566
+
- name: FLEET_GITHUB_APP_CLIENT_ID
567
+
value: "<client-id>"
568
+
- name: FLEET_GITHUB_APP_CLIENT_SECRET
569
+
valueFrom:
570
+
secretKeyRef:
571
+
name: fleet-github-app
572
+
key: client_secret
573
+
- name: FLEET_GITHUB_APP_PRIVATE_KEY
574
+
valueFrom:
575
+
secretKeyRef:
576
+
name: fleet-github-app
577
+
key: private_key
578
+
- name: FLEET_GITHUB_APP_WEBHOOK_SECRET
579
+
valueFrom:
580
+
secretKeyRef:
581
+
name: fleet-github-app
582
+
key: webhook_secret
583
+
- name: FLEET_GITHUB_APP_STATE_JWT_SECRET
584
+
valueFrom:
585
+
secretKeyRef:
586
+
name: fleet-github-app
587
+
key: state_jwt_secret
588
+
589
+
agentBuilderToolServer:
590
+
deployment:
591
+
extraEnv:
592
+
- name: FLEET_GITHUB_APP_ENABLED
593
+
value: "true"
594
+
```
595
+
596
+
<Note>
597
+
`FLEET_GITHUB_APP_ENABLED` must be set on the tool server so the GitHub tools are registered. The remaining `FLEET_GITHUB_APP_*` variables are consumed by the platform backend and so live under `commonEnv`.
598
+
</Note>
599
+
</Step>
600
+
601
+
<Step title="Deploy and install the app on repositories">
602
+
Upgrade your LangSmith release to apply the new configuration. Once pods are healthy:
603
+
604
+
1. In LangSmith, open a Fleet agent and go to the GitHub integration in the agent editor.
605
+
2. Click **Connect GitHub** to install the app on the repositories Fleet should access.
606
+
3. For private repositories, you must explicitly select each repository during installation.
607
+
608
+
<Note>
609
+
Users must also authorize the app against their own GitHub account (via the re-auth flow in LangSmith) so Fleet can resolve per-user tokens for tools that act on behalf of a user.
610
+
</Note>
611
+
</Step>
612
+
</Steps>
613
+
498
614
## Disable Fleet
499
615
500
616
To disable Fleet, set the following to `false` in your `values.yaml`:
0 commit comments