From cc4eaff2483158ebeb2be4c257e4519841d1d707 Mon Sep 17 00:00:00 2001 From: Matt Vollmer Date: Thu, 16 Apr 2026 15:52:17 -0400 Subject: [PATCH] docs: add git providers and PR Insights pages for Coder Agents (#24447) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../agents/platform-controls/git-providers.md | 55 +++++++++++++++++ .../agents/platform-controls/index.md | 16 +++++ .../agents/platform-controls/pr-insights.md | 61 +++++++++++++++++++ docs/manifest.json | 12 ++++ 4 files changed, 144 insertions(+) create mode 100644 docs/ai-coder/agents/platform-controls/git-providers.md create mode 100644 docs/ai-coder/agents/platform-controls/pr-insights.md diff --git a/docs/ai-coder/agents/platform-controls/git-providers.md b/docs/ai-coder/agents/platform-controls/git-providers.md new file mode 100644 index 0000000000..6a7aef7212 --- /dev/null +++ b/docs/ai-coder/agents/platform-controls/git-providers.md @@ -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. diff --git a/docs/ai-coder/agents/platform-controls/index.md b/docs/ai-coder/agents/platform-controls/index.md index 292c08f132..7bec338c43 100644 --- a/docs/ai-coder/agents/platform-controls/index.md +++ b/docs/ai-coder/agents/platform-controls/index.md @@ -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. diff --git a/docs/ai-coder/agents/platform-controls/pr-insights.md b/docs/ai-coder/agents/platform-controls/pr-insights.md new file mode 100644 index 0000000000..9436569ed0 --- /dev/null +++ b/docs/ai-coder/agents/platform-controls/pr-insights.md @@ -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. diff --git a/docs/manifest.json b/docs/manifest.json index e7b20d231f..3209b70021 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -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",