Pluggable source control providers (custom CLI-backed providers for unsupported hosts)

[vanilla-wave]

Problem

Both the VCS layer (VcsDriverKind: git, jj) and the source control provider layer (SourceControlProviderKind: github, gitlab, forgejo, azure-devops, bitbucket) are closed enums. The provider is picked from a hardcoded hostname match on the remote URL. A repository hosted on anything else, such as an internal or less common code review system, is classified as unknown, and the change request features (create, list, status, checkout) don't work for it.

Today the only way to get support is to add it to core or keep a fork. A fork is painful because the enums sit in packages/contracts and are shared by the server and the client, so almost every nightly conflicts with it.

Proposal

Add a minimal extension point for source control providers (and, possibly later, VCS drivers) that doesn't require changes to core. For example:

• User-level config that maps a remote host pattern to a custom provider
• The custom provider is a CLI or script with a small, documented contract, e.g. JSON in and JSON out for create, list, view, status, and checkout, much like the built-in providers already wrap gh, glab, and az
• Graceful degradation: operations the provider doesn't implement stay hidden, as they are for unknown today

This is a narrower, concrete slice of the general extension system discussed in #6714, and it relates to the VCS pluggability question raised in #7033.

Why

It lets people use T3 Code with hosting and review systems that will never get first-class support, without forking and without adding maintenance cost to core.

[theskillwithin]

+1. Here's a concrete case: Repopack is a self-hosted git and agent-task platform. Its remotes look like ssh://git@repopack.com/project/<name>, so T3 Code classifies them as unknown.

What we do for now: Repopack serves a PR-shaped alias, /project/<name>/pulls/<n>, which redirects to the task page. parseChangeRequestUrl accepts the Forgejo /pulls/<n> shape on any host, so agents can register it with link_pull_request. The link shows up on the thread, but state, title and the branches stay null, and the thread never settles on merge, because there's no provider for the host. Opening the linked PR in the panel shows "Could not load pull requests. Change requests cannot be browsed for this project's host yet." (provider-unsupported).

The CLI contract you describe would close that gap for us. Our CLI already returns what a provider would need (rp --json task show <n>: state, title, head/base branch). Only a few operations matter for linking:

• view / status for a linked number: state (open/merged/closed), title, and head/base branch
• list --head <branch>: to auto-detect the change request for a thread's branch

create and checkout could stay optional. That fits the graceful degradation you suggest.

The existing refineUnknownRemoteProvider step might be a natural hook: an unknown host already gets probed through CLI discovery specs, so a user-configured host → command mapping could plug in there.

[Jonathanm10]

+1. Here's a concrete case: Azure DevOps Server (on-prem), which #14105 was folded into.

The built-in Azure provider goes through az, and Microsoft says the Azure DevOps CLI "works only with Azure DevOps Services (cloud). It doesn't support Azure DevOps Server (on-premises)" (docs). Since #14626, Server pull request links are recognised, but listing, status, sync and creation all stay provider-unsupported.

I've run a Server provider in a fork (Jonathanm10/t3code-azure-nightly) against a corporate server for a few days. What it needed:

1. REST, not a CLI. api-version 6.0 (Server 2020 and later), on collection-scoped remotes such as https://host/tfs/<Collection>/<Project>/_git/<Repo>.
2. No new secret. It authenticates with the credential git already uses for the remote (git credential fill), so T3 stores no PAT.
3. Separate API and browser hosts. Our git/API host differs from the web host (git.example.com vs tfs.example.com), so pull request web URLs need a per-collection mapping. GitLab hits the same split in [Bug]: Split SSH/API hostnames leave self-hosted GitLab MR links unsynced #16463.
4. A small set of operations. List, view and status cover sync and auto-settle; create covers "Create PR". Merge, review and checkout can stay hidden.

The cost of keeping it in a fork is the one this discussion describes. The provider kind and settings sit in shared contracts, so the fork needed six hand-resolved upstream merges in three days to keep releasing.

Which direction would you accept?

• A pluggable provider contract (this discussion). I'd move the Server provider onto it, outside core.
• A first-class Azure DevOps Server provider in core: REST plus git credentials, read operations first, create later.

Once you pick one, I can propose a small first PR scoped to it.

[luquibu]

+1 from another Azure DevOps Server shop, with two details that differ from the fork described above.

Setup: Azure DevOps Server 2022.2 on-prem, domain-joined Windows 11 clients, T3 Code desktop 0.1.2. We want the same read slice: find the PR for a thread's branch, show its status, and settle the thread on merge. Since #14626 we can link PRs by URL, but they stay provider-unsupported.

1. No /tfs/ segment. Our collection is served at the site root: https://<host>/<Collection>/<Project>/_git/<Repo> (connectionData reports webApplicationRelativeDirectory: "<Collection>/"). Detection should key off the /_git/ segment rather than a /tfs/ prefix. Git, REST and the web UI share one host here, so we need no browser-host mapping.
2. Windows Integrated Authentication, no stored credential. Git reaches the server through Git Credential Manager's generic provider using Windows auth, and Windows Credential Manager holds no entry for the host, so git credential fill likely has no secret to hand over. The REST API accepts Negotiate (curl --negotiate -u : works with the domain session; anonymous requests get 401). A provider that relies only on git credential fill would not authenticate in setups like ours. Supporting Negotiate/NTLM on Windows, with an optional PAT, would cover both.

az is not an option for Server: Microsoft's docs state the Azure DevOps CLI does not support Azure DevOps Server.

Either direction (a pluggable contract or a first-class provider) works for us, and read operations alone would cover what we need.

[Thanaen]

+1 from a third Azure DevOps Server shop. We need the same read-only part as the comments above.

Our setup: an on-prem Azure DevOps Server 2022, with an upgrade to the latest release planned soon. The collection is served at the site root, https://<host>/DefaultCollection/<Project>/_git/<Repo>. There is no /tfs/ segment, and git, the REST API and the web UI all use the same host. The REST API accepts a PAT, which is what our other tools already use.

What we need: find the PR for a thread's branch, show its title and state, and settle the thread when the PR is merged or abandoned. Creating, merging and reviewing PRs can stay hidden.

What we can do: we're happy to implement this read-only part, using the REST API with a PAT and optionally the git credential, in whichever direction you prefer: on the pluggable contract proposed here, or as a first-class Azure DevOps Server provider. A short note on the direction and scope you'd accept is enough for us to start with a small first PR.

[jean-humann]

A read-only first slice, and one contract for the hosts that keep landing here

Since #17739 and the source-control boundary stack (#23992–#24288), the provider kind is an open slug and each forge is a package that answers neutral hooks. What stays closed is the list: drivers and client definitions are compiled in, so any other host is unknown. The asks in this thread (Repopack; three Azure DevOps Server shops with /tfs/ or root collections and PAT, git-credential or Negotiate auth), plus Bitbucket DC (#23325), SourceHut (#22030), Codeup (#18546), Brnch (#21330), Tangled (#18710) and a self-hosted forge we run, need the same few reads. None of them needs code in core.

Proposal. One more built-in driver, external-command. Each user-configured entry gives a provider under a stable kind. Every call runs a fixed argv plus one verb, with a JSON request on stdin and one JSON object on stdout. protocol: 1 is negotiated by hello, and exit codes 0–4 map onto PullRequestProviderError.reason. It fills the existing source-control-core hooks and leaves every other operation absent. No plugin runtime, no JS loading, no manifest.

flowchart LR
  C["Clients"] -->|WebSocket| S["T3 server<br/>PullRequestService"]
  S --> D["external-command driver<br/>(one per configured entry)"]
  D -->|"verb + JSON on stdin"| X["adapter CLI"]
  X -->|"one JSON object, exit 0–4"| D
  X -->|"its own credentials"| H["source control host"]

Loading

Safety. The entry lives in server settings, gated by providers:manage like an agent binaryPath. It is never in t3.json and never in MCP. The executable is resolved to a real path outside any project and runs from a neutral directory, with no shell, no .cmd and a filtered environment. Output is decoded against bounded schemas, and URLs must sit under the repository's web origin. The command keeps its own credentials.

Clients. The entry carries a small data descriptor: label, terminology, hosts and path templates such as /{collection}/{project}/_git/{repo}/pullrequest/{number} (templates, not regexes, so they parse and build). One shared function compiles it into a SourceControlDefinition. Clients get it as an optional, cached ServerConfig field and apply it only to that environment's links.

Slices. 0: make the server's definition registry a service (no behaviour change; today it is a module constant read by ~25 files). 1, behind a flag: the driver; a configured host wins over built-in path heuristics (/_git/, /pulls/<n>); find a branch's change request, view and sync it, settle the thread on merge or close; plus a two-line fix so a provider that names a different web host is listed on it. 2: descriptors to clients. Along the way we noticed that unparsed change-request URLs fall back to GitHub wording; we'd fix that in slice 2.

Full design (contract v1 with JSON examples, errors and limits, configuration, threat model and safeguards, slices): https://gist.github.com/jean-humann/460ae76fc8d5d7bd67ed761c2d056aea

@juliusmarminge, would you accept slices 0 and 1 as scoped, behind a flag, with you free to take them over? It is the driver a future plugin would register, not a competing runtime.