Skip to content

馃攢 docs: Document Pull Request Providers, Hosts and Per-User Accounts #821

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
berry-13 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

馃攢 docs: Document Pull Request Providers, Hosts and Per-User Accounts #821

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 28 additions & 11 deletions content/docs/configuration/dotenv.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1584,38 +1584,53 @@ Named attached environments can also expose a self-service pairing control plane

## Conversation Pull Requests

Settings for showing a conversation's GitHub pull request. See [Conversation Pull Requests](/docs/features/pull_requests) and [`endpoints.agents.pullRequests`](/docs/configuration/librechat_yaml/object_structure/agents#pullrequests).
Settings for showing a conversation's pull request from GitHub, GitLab or Bitbucket Cloud. See [Conversation Pull Requests](/docs/features/pull_requests) and [`endpoints.agents.pullRequests`](/docs/configuration/librechat_yaml/object_structure/agents#pullrequests).

<Callout type="important" title="Pending: not yet released">
The three fallback token variables are part of LibreChat-AI/LibreChat#16876. In older versions,
set the variable that `token: "${NAME}"` refers to.
</Callout>
The fallback variables are used only when `pullRequests.token` is not set, and only those of the configured `provider` are read, in the order listed. Set them on the LibreChat server.

<OptionTable
options={[
[
'GITHUB_PULL_REQUEST_TOKEN',
'string',
'Pending. Fallback read-only GitHub token when `pullRequests.token` is not set. Tried first. Set on the LibreChat server.',
'Fallback read-only GitHub token. Tried first on GitHub.',
'# GITHUB_PULL_REQUEST_TOKEN=your-read-only-token',
],
[
'GITHUB_TOKEN',
'string',
'Pending. Fallback token, tried second. It is a common name: if your deployment already uses it for something else, the fallback starts using it here as soon as a repository scope is set.',
'Fallback GitHub token, tried second. It is a common name: if your deployment already uses it for something else, the fallback starts using it here as soon as a repository scope is set.',
'# GITHUB_TOKEN=your-read-only-token',
],
[
'GH_TOKEN',
'string',
'Pending. Fallback token, tried third.',
'Fallback GitHub token, tried third.',
'# GH_TOKEN=your-read-only-token',
],
[
'GITLAB_PULL_REQUEST_TOKEN',
'string',
'Fallback GitLab token with the `read_api` scope. Tried first on GitLab.',
'# GITLAB_PULL_REQUEST_TOKEN=your-read-api-token',
],
[
'GITLAB_TOKEN',
'string',
'Fallback GitLab token, tried second. Also a common name; see `GITHUB_TOKEN`.',
'# GITLAB_TOKEN=your-read-api-token',
],
[
'BITBUCKET_PULL_REQUEST_TOKEN',
'string',
'Pending. Fallback Bitbucket Cloud repository, project or workspace access token with read access to pull requests and repositories.',
'# BITBUCKET_PULL_REQUEST_TOKEN=your-read-only-token',
],
[
'Any name you choose',
'string',
'The variable that `pullRequests.token: "${NAME}"` refers to. Set on the LibreChat server.',
'# MY_GITHUB_TOKEN=your-read-only-token',
'The variable that `pullRequests.token: "${NAME}"` refers to. Also used for `pullRequests.oauth.clientId` and `clientSecret` (Pending), which are references too.',
'# GITHUB_PR_OAUTH_CLIENT_ID=your-client-id',
],
[
'CODEAPI_BRIDGE_LANE_GIT',
Expand All @@ -1626,7 +1641,9 @@ Settings for showing a conversation's GitHub pull request. See [Conversation Pul
]}
/>

GitHub requests use the deployment's proxy settings (`PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and their lowercase forms), and `NO_PROXY` is honored. These are shared with other LibreChat outbound traffic and are not specific to this feature.
Users connecting their own account (Pending) need `JWT_SECRET`, which signs the connection flow, and `DOMAIN_SERVER`, which forms the callback URL `<DOMAIN_SERVER>/api/pull-requests/oauth/callback`. `pullRequests.sharedCache` (Pending) takes effect only with `USE_REDIS=true`.

Provider requests use the deployment's proxy settings (`PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and their lowercase forms), and `NO_PROXY` is honored. These are shared with other LibreChat outbound traffic and are not specific to this feature.

## Artifacts

Expand Down
125 changes: 105 additions & 20 deletions content/docs/configuration/librechat_yaml/object_structure/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -552,48 +552,66 @@ Event Actor detached Action completion is selected automatically from the built-

## pullRequests

{/* Pending items (LibreChat-AI/LibreChat#16876): delete the "Older versions" notes and Pending markers once it merges. Re-verify defaults and ranges against packages/data-provider/src/config.ts. */}
{/* Pending items: Bitbucket Cloud (LibreChat-AI/LibreChat#16987), sharedCache (#16988) and oauth (#16989, #16990). Delete the Pending markers once each merges. Re-verify defaults and ranges against packages/data-provider/src/config.ts. */}

Shows the GitHub pull request for a conversation's attached code workspace in the chat header and sidebar. See [Conversation Pull Requests](/docs/features/pull_requests) for setup, behavior and troubleshooting. Every key is optional.
Shows the pull request (a merge request on GitLab) for a conversation's attached code workspace in the chat header and sidebar. See [Conversation Pull Requests](/docs/features/pull_requests) for setup, behavior and troubleshooting. Every key is optional.

Most administrators set only a token, a repository scope, and possibly `enabled: false`. The remaining keys are for tuning, and their defaults are fine.
The feature is on as soon as the server has a token and a repository scope, or users can connect their own accounts through `oauth`. Most administrators set only a repository scope and a token, plus `provider` and `host` when not on github.com. The tuning keys' defaults are fine.

<Callout type="important" title="Pending: not yet released">
Default-on behavior, the environment variable token fallback, and `allowAllRepositories` are part
of LibreChat-AI/LibreChat#16876. In older versions `enabled` defaults to `false` and `token` is
required.
<Callout type="info" title="Read from librechat.yaml only">
`provider`, `host` and `oauth` are read from `librechat.yaml` alone. Role, group, user and tenant
config overrides of these keys are ignored, so an override cannot redirect a token to another
service.
</Callout>

<OptionTable
options={[
[
'enabled',
'Boolean',
'Set `false` to turn the feature off. Pending: it is on once a token and a repository scope exist. Older versions: defaults to `false`, and `true` requires `token` and a non-empty `allowedRepositories`.',
'Set `false` to turn the feature off. Otherwise it is on once a token and a repository scope exist, or an `oauth` app resolves.',
'enabled: false',
],
[
'provider',
'String',
'`github` (default), `gitlab` for merge requests on gitlab.com or a self-managed GitLab, or `bitbucket` for Bitbucket Cloud (Pending). Read from the YAML only.',
'provider: "gitlab"',
],
[
'host',
'String',
'Host name the token belongs to, without scheme or path: a GitHub Enterprise Server host, a `*.ghe.com` tenant, or a self-managed GitLab host. A port from 1 to 65535 is allowed, and `:443` is dropped. Defaults to `github.com`, `gitlab.com` or `bitbucket.org` for the provider. Bitbucket accepts no other host. Read from the YAML only.',
'host: "github.example.com"',
],
[
'token',
'String',
'Reference to an environment variable that holds a read-only GitHub token, in the form `${NAME}`. Never the token itself. Pending: when unset, the server uses the first of `GITHUB_PULL_REQUEST_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN` that is set. A `token` that does not resolve fails with `NOT_CONFIGURED` and does not fall back. Older versions: required.',
'Reference to an environment variable that holds a read-only token, in the form `${NAME}`. Never the token itself. When unset, the first fallback variable that is set is used: `GITHUB_PULL_REQUEST_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN` on GitHub; `GITLAB_PULL_REQUEST_TOKEN`, `GITLAB_TOKEN` on GitLab; `BITBUCKET_PULL_REQUEST_TOKEN` on Bitbucket. A `token` that does not resolve fails with `NOT_CONFIGURED` and does not fall back.',
'token: "${GITHUB_PULL_REQUEST_TOKEN}"',
],
[
'oauth',
'Object',
'Pending. Lets each user connect their own account, so lookups use that user\'s token, rate limit and repository access. Read from the YAML only. See [oauth](#pullrequestsoauth) below.',
'oauth: { clientId: "${GITHUB_PR_OAUTH_CLIENT_ID}", clientSecret: "${GITHUB_PR_OAUTH_CLIENT_SECRET}" }',
],
[
'allowedRepositories',
'Array of Strings',
'Repositories the token may be used for, as `owner/name` or `owner/*` (up to 256 entries, case-insensitive). `*/*`, `*`, `owner`, and entries containing `..` are rejected.',
'Repositories the server token may be used for, as `owner/name` or `owner/*` (up to 256 entries, case-insensitive). On GitLab, nested group paths such as `group/sub/name` or `group/sub/*` are allowed; `*` matches one segment. `*/*`, `*`, `owner`, and entries with `.` or `..` segments are rejected.',
'allowedRepositories: ["LibreChat-AI/LibreChat", "my-org/*"]',
],
[
'allowAllRepositories',
'Boolean',
'Pending. Look up any repository the token can read. Default: `false`. See the warning below.',
'Look up any repository the server token can read. Default: `false`. See the warning below.',
'allowAllRepositories: false',
],
[
'cacheTtlSeconds',
'Number',
'Seconds a result is reused before GitHub is asked again (5-3600). Failures are remembered for at most 10 seconds. Default: 30.',
'Seconds a result is reused before the provider is asked again (5-3600). Failures are remembered for at most 10 seconds. Default: 30.',
'cacheTtlSeconds: 30',
],
[
Expand All @@ -605,13 +623,13 @@ Most administrators set only a token, a repository scope, and possibly `enabled:
[
'cacheMaxCredentials',
'Number',
'Credentials cached at once, deployment-wide (1-10000). The one idle longest is dropped past it. When principals set different values, the largest applies. Raise it when many tenants each use their own token. Default: 256.',
'Credentials cached at once, deployment-wide (1-10000). The one idle longest is dropped past it. When principals set different values, the largest applies. Raise it when many tenants each use their own token, or many users connect their own accounts. Default: 256.',
'cacheMaxCredentials: 256',
],
[
'maxConcurrentLookups',
'Number',
'Lookups one sidebar request runs at once (1-16), counted per credential across requests. Each lookup is a few GitHub requests. Default: 4.',
'Lookups one sidebar request runs at once (1-16), counted per credential across requests. Each lookup is a few provider requests. Default: 4.',
'maxConcurrentLookups: 4',
],
[
Expand All @@ -623,7 +641,7 @@ Most administrators set only a token, a repository scope, and possibly `enabled:
[
'requestTimeoutSeconds',
'Number',
'Longest one GitHub request may take (1-60). Raise it behind a slow proxy. Default: 10.',
'Longest one provider request may take (1-60). Raise it behind a slow proxy. Default: 10.',
'requestTimeoutSeconds: 10',
],
[
Expand All @@ -635,7 +653,7 @@ Most administrators set only a token, a repository scope, and possibly `enabled:
[
'maxCheckRunPages',
'Number',
'Pages of 100 check runs read before the rollup is reported as still running (1-50). Default: 10.',
'Pages of check runs (GitHub) or commit statuses (Bitbucket) read before checks are reported as still running (1-50). GitLab reads the head pipeline instead. Default: 10.',
'maxCheckRunPages: 10',
],
[
Expand All @@ -656,13 +674,25 @@ Most administrators set only a token, a repository scope, and possibly `enabled:
'Candidates compared with the commit the chat last ran at before the search gives up (0-20). Each comparison is one request. `0` disables comparing. Default: 3.',
'maxHeadComparisons: 3',
],
[
'sharedCache',
'Boolean',
'Pending. Share looked-up pull requests and rate limit cooldowns between replicas through Redis. Takes effect only with `USE_REDIS`; each replica keeps its own in-memory cache either way. Default: `false`.',
'sharedCache: true',
],
[
'sharedCacheTimeoutMs',
'Number',
'Pending. Longest one shared cache read or write may take, in milliseconds, before the lookup carries on without it (10-5000). Default: 250.',
'sharedCacheTimeoutMs: 250',
],
]}
/>

<Callout type="warning" title="Security: allowAllRepositories">
With this on, any user who can run code can point the server's token at any repository that token
can read, and see the pull request title, size and check status. Use a read-only token scoped to
the repositories you are willing to show.
The worker reports its own repository, so with this on, any user who can run code can point the
server's token at any repository that token can read, and see the pull request title, size and
check status. Use a read-only token scoped to the repositories you are willing to show.
</Callout>

```yaml filename="endpoints / agents / pullRequests"
Expand All @@ -677,7 +707,62 @@ endpoints:
maxConcurrentLookups: 4
```

On older versions, add `enabled: true`.
### pullRequests.oauth

Pending. Lets each user connect their own account under **Settings > Account > Pull request account**. A connected user's lookups use their own token and are not held to `allowedRepositories`; users who have not connected keep using the server token. Register `<DOMAIN_SERVER>/api/pull-requests/oauth/callback` as the app's callback URL. On GitHub, a GitHub App with read-only Pull requests, Checks and Contents permissions is recommended. See [Per-user accounts](/docs/features/pull_requests#per-user-accounts).

<OptionTable
options={[
[
'clientId',
'String',
'Required. Environment variable reference to the app\'s client ID, in the form `${NAME}`.',
'clientId: "${GITHUB_PR_OAUTH_CLIENT_ID}"',
],
[
'clientSecret',
'String',
'Required. Environment variable reference to the app\'s client secret, in the form `${NAME}`.',
'clientSecret: "${GITHUB_PR_OAUTH_CLIENT_SECRET}"',
],
[
'scope',
'String',
'Space separated scopes to request, up to 256 characters. Defaults: none on GitHub, `read_api` on GitLab, and the consumer\'s own permissions on Bitbucket. Set it only for a classic GitHub OAuth App.',
'scope: "repo"',
],
[
'flowTimeoutMinutes',
'Number',
'Minutes a user may take to approve the connection at the provider (1-60). Default: 10.',
'flowTimeoutMinutes: 10',
],
[
'requestTimeoutSeconds',
'Number',
'Seconds a code exchange or token refresh may take (1-60). Default: 10.',
'requestTimeoutSeconds: 10',
],
[
'retentionDays',
'Number',
'Days a connection is kept without being used (1-3650). Every use extends it. Default: 180.',
'retentionDays: 180',
],
]}
/>

If either reference does not resolve, users cannot connect and only the server token is used.

```yaml filename="endpoints / agents / pullRequests / oauth"
endpoints:
agents:
pullRequests:
oauth:
clientId: '${GITHUB_PR_OAUTH_CLIENT_ID}'
clientSecret: '${GITHUB_PR_OAUTH_CLIENT_SECRET}'
retentionDays: 180
```

## backgroundTasks

Expand Down
2 changes: 1 addition & 1 deletion content/docs/features/code_interpreter.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Agents using an attached workspace can list its directory tree, read files, sear

In the chat, a failed attached-workspace Bash command shows its exit code, terminating signal, or timeout, and its stderr is styled separately from stdout. See [Activity Groups](/docs/features/agents#activity-groups) for how Bash output is displayed.

To show a conversation's GitHub pull request in the chat header and sidebar, the attached worker must report its git branch. That needs a worker built from `LibreChat-AI/code-interpreter` PR #311 or later and `CODEAPI_BRIDGE_LANE_GIT=true` set on the Code API (not on LibreChat). See [Conversation Pull Requests](/docs/features/pull_requests).
To show a conversation's pull request (GitHub, GitLab or Bitbucket Cloud) in the chat header and sidebar, the attached worker must report its git branch. That needs a worker built from `LibreChat-AI/code-interpreter` PR #311 or later and `CODEAPI_BRIDGE_LANE_GIT=true` set on the Code API (not on LibreChat). See [Conversation Pull Requests](/docs/features/pull_requests).

An attached worker advertises the workspace roots it makes available. The composer lets the user select one workspace for each attached environment reachable through the Agent or its Subagents; a single unambiguous workspace is selected automatically for a new conversation. LibreChat stores these selections on the conversation, revalidates them against the live worker before execution, and keeps them fixed through approval pauses and resumed runs. Sending is blocked when a required selection is missing or unavailable, and LibreChat never silently substitutes another workspace. At the start of a run, LibreChat can load repository instructions from the selected workspace so the Agent follows that repository's guidance; administrators can bound discovery with [`repositoryInstructions.timeoutMs`](/docs/configuration/librechat_yaml/object_structure/agents#repositoryinstructions). Native file and Bash workspace tools can use an advertised root even when the worker does not support reusable runtime sessions. Workspace-aware Programmatic Bash is available on compatible Code API and worker builds when the Agent's programmatic-tool configuration permits it, the authorized attached worker is ready and advertises `programmaticLanguages: ['bash']`, and both the selected workspace and worker allow `execute_command`. LibreChat passes the server-validated workspace ID and conversation workspace-instance ID, when present, to the programmatic tool; model arguments cannot replace that selection. Without these capabilities, Programmatic Bash is disabled; use direct Bash for workspace-aware commands. When the worker supports file relay, chat uploads are staged separately under `$LIBRECHAT_CODE_DATA_DIR` for the programmatic run, not copied into the selected workspace. **Stop** cancels a signal-aware in-flight BYOM command without invalidating the workspace for later commands; detached work retains its separate cancellation lifecycle.

Expand Down
Loading
Loading