mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
docs: add git providers and PR Insights pages for Coder Agents (#24447)
Adds two new documentation pages under platform controls for Coder Agents: - **Git Providers** (`git-providers.md`) — documents the `API_BASE_URL` configuration required for self-hosted GitHub Enterprise deployments. Positions it as an extension of the existing [external auth](https://coder.com/docs/admin/external-auth) setup to support Coder Agents features that need richer git host API access: the in-chat diff viewer and PR Insights. - **PR Insights** (`pr-insights.md`) — documents the PR analytics dashboard, requirements for PR data to appear, and troubleshooting. Links to git-providers for GHE setup. Also updates the platform controls index and docs manifest. --- > PR generated with Coder Agents
This commit is contained in:
Matt Vollmer
@@ -0,0 +1,55 @@
|
||||
# Git Providers
|
||||
|
||||
Coder Agents leverages your existing
|
||||
[external authentication](../../../admin/external-auth/index.md) configuration
|
||||
to power the in-chat diff viewer and [PR Insights](./pr-insights.md).
|
||||
Self-hosted GitHub Enterprise deployments require one additional setting
|
||||
(`API_BASE_URL`) for these features to work.
|
||||
|
||||
> [!NOTE]
|
||||
> Only `github` type external auth providers are supported today.
|
||||
|
||||
## GitHub Enterprise configuration
|
||||
|
||||
For public `github.com`, no additional configuration is needed.
|
||||
|
||||
For self-hosted GitHub Enterprise, add `API_BASE_URL` to your
|
||||
[existing configuration](../../../admin/external-auth/index.md#github-enterprise):
|
||||
|
||||
```env
|
||||
CODER_EXTERNAL_AUTH_0_ID="primary-github"
|
||||
CODER_EXTERNAL_AUTH_0_TYPE=github
|
||||
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
|
||||
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
|
||||
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
|
||||
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
|
||||
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/api/v3/user"
|
||||
CODER_EXTERNAL_AUTH_0_API_BASE_URL="https://github.example.com/api/v3"
|
||||
CODER_EXTERNAL_AUTH_0_REGEX=github\.example\.com
|
||||
```
|
||||
|
||||
Without `API_BASE_URL`, Coder defaults to `https://api.github.com`. Clone
|
||||
and push still work (they use `AUTH_URL` and `TOKEN_URL` directly), but
|
||||
the diff viewer and PR Insights silently fail because Coder builds its
|
||||
URL-matching patterns from the API base URL.
|
||||
|
||||
> [!NOTE]
|
||||
> If you have both a `github.com` and a GHE external auth config, only the
|
||||
> GHE config needs `API_BASE_URL`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Diffs or PR data not appearing on GHE
|
||||
|
||||
Add `API_BASE_URL` to your GHE external auth config and restart Coder.
|
||||
Data should appear within a couple of minutes.
|
||||
|
||||
### Users not seeing diffs
|
||||
|
||||
The chat owner must have linked their account through the relevant external
|
||||
auth provider.
|
||||
|
||||
### Checking logs
|
||||
|
||||
Look for gitsync warnings such as `no provider for origin` or
|
||||
`resolve token` errors.
|
||||
@@ -137,6 +137,22 @@ breakdowns.
|
||||
|
||||
See [Spend Management](./usage-insights.md) for details.
|
||||
|
||||
### Git providers
|
||||
|
||||
Coder Agents leverages your existing
|
||||
[external authentication](../../../admin/external-auth/index.md) configuration to
|
||||
power the in-chat diff viewer and PR Insights. Self-hosted GitHub Enterprise
|
||||
deployments require additional configuration for these features.
|
||||
|
||||
See [Git Providers](./git-providers.md) for details.
|
||||
|
||||
### PR Insights
|
||||
|
||||
PR Insights tracks pull requests created by Coder Agents and surfaces
|
||||
analytics on PR activity, merge rates, and cost efficiency.
|
||||
|
||||
See [PR Insights](./pr-insights.md) for requirements and dashboard details.
|
||||
|
||||
### Data retention
|
||||
|
||||
Administrators can configure a retention period for archived conversations.
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# PR Insights
|
||||
|
||||
PR Insights tracks pull requests created by Coder Agents and surfaces
|
||||
analytics on PR activity, merge rates, and cost efficiency. The dashboard
|
||||
(under **Agents** > **Insights** > **PR Insights**) shows merge rates,
|
||||
cost per merged PR, per-model breakdowns, and individual PR status.
|
||||
|
||||
## How it works
|
||||
|
||||
A background worker monitors active agent chats for git activity. When an
|
||||
agent pushes a branch or creates a pull request, the worker resolves the git
|
||||
remote origin against configured external auth providers.
|
||||
|
||||
The worker uses the matched provider's API to fetch PR metadata: status, diff
|
||||
stats, review state, and merge outcome.
|
||||
|
||||
> [!NOTE]
|
||||
> Only `github` type external auth providers are supported for PR Insights
|
||||
> today.
|
||||
|
||||
## Requirements
|
||||
|
||||
For PR data to appear in analytics, all of the following must be true:
|
||||
|
||||
1. **External auth is configured for your git host** — The external auth
|
||||
config must have `type` set to `github` with a regex matching your
|
||||
repository URLs. See
|
||||
[External Authentication](../../../admin/external-auth/index.md).
|
||||
|
||||
1. **Users have linked their external auth** — The user who ran the agent
|
||||
task must have authenticated with the relevant external auth provider.
|
||||
Without a linked token, the worker cannot fetch PR data and retries on a
|
||||
backoff schedule.
|
||||
|
||||
1. **The agent reported a git reference** — The agent must push to a branch
|
||||
with a configured remote origin. If no branch or remote origin is
|
||||
reported, the worker skips the chat.
|
||||
|
||||
For self-hosted GitHub Enterprise deployments, additional configuration is
|
||||
required. See [Git Providers](./git-providers.md#github-enterprise-configuration).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### PRs not appearing
|
||||
|
||||
Verify the user has linked their external auth. Check Coder logs for gitsync
|
||||
warnings like `no provider for origin` or token resolution errors. For GitHub
|
||||
Enterprise, confirm that `API_BASE_URL` is set — see
|
||||
[Git Providers](./git-providers.md#troubleshooting).
|
||||
|
||||
### Only github.com PRs appear
|
||||
|
||||
If you have multiple external auth configs (e.g., `github.com` + GHE),
|
||||
ensure the GHE config has `API_BASE_URL` set. The `github.com` config works
|
||||
without it because the default is already correct.
|
||||
|
||||
### PR data delayed
|
||||
|
||||
The background worker polls on a ~10 second interval. New PRs typically
|
||||
appear within a couple of minutes. If a token refresh fails, the worker
|
||||
backs off for 10 minutes before retrying.
|
||||
@@ -1251,6 +1251,18 @@
|
||||
"path": "./ai-coder/agents/platform-controls/usage-insights.md",
|
||||
"state": ["early access"]
|
||||
},
|
||||
{
|
||||
"title": "Git Providers",
|
||||
"description": "Git provider configuration for the diff viewer and PR Insights",
|
||||
"path": "./ai-coder/agents/platform-controls/git-providers.md",
|
||||
"state": ["early access"]
|
||||
},
|
||||
{
|
||||
"title": "PR Insights",
|
||||
"description": "Pull request analytics for Coder Agents",
|
||||
"path": "./ai-coder/agents/platform-controls/pr-insights.md",
|
||||
"state": ["early access"]
|
||||
},
|
||||
{
|
||||
"title": "Data Retention",
|
||||
"description": "Automatic cleanup of old conversation data",
|
||||
|
||||
Reference in New Issue
Block a user