← Workstreams

Workstream: Git

Status: Planned · Component: Maximize developer productivity

Goal

Make Git a first-class, platform-integrated capability rather than something each service wires up by hand. Three things should be effortless for any service, CLI, or agent:

  1. Host repositories ourselves — serve Git over SSH on our own infrastructure, independent of any third party.
  2. Talk to GitHub programmatically — query and mutate repos, issues, and pull requests without each consumer holding tokens or learning the raw GitHub API.
  3. React to repository changes — know when a repo changed without polling.

Together these mean source control is a capability the platform provides, not a per-service integration chore — which matters enormously once agents are managing code.

Current state

The pieces exist across four sub-areas:

Sub-area Repositories What it provides
Self-hosted Git over SSH git-javagitsshserver A lightweight Git SSH server (Apache MINA SSHD + Eclipse JGit) supporting git clone/fetch/push with public-key auth and per-repository access control
Deployed Git host javagitsshserver The running Git-over-SSH instance hosting bare repositories on our own server (Git serves on the standard SSH port; interactive ssh is moved aside)
GitHub API proxy GithubProxyApi · GithubProxyServerService · GithubProxyCli url://githubproxy/ proxies GitHub operations (users, repos, issues, PRs, close/merge) so consumers never hold tokens; the CLI mirrors gh (aiming to be a drop-in gh an agent can use unchanged). See the GithubProxy project doc, and the GithubProxy plan for the W3Wallet-gated key-registration model and the drop-in-gh CLI
Repo change tracking GithubWatchman (Api / ServiceServer / IntegrationServer / Cli / Wui) url://github-watchman/ records invalidation timestamps from GitHub webhooks so systems detect changes without polling

So most of the machinery is built; this workstream is about unifying it into one coherent "Git" capability and closing the gaps between the parts.

Why it accelerates developers

  • No token sprawl. GithubProxy keeps GitHub credentials in one service; consumers (and agents) call url://githubproxy/ instead of each managing a PAT.
  • No polling. GithubWatchman turns "did this repo change?" into a webhook-driven invalidation, which already powers refresh callbacks (e.g. via LambdaServer) for Dependabot, GitProjectHealth, and PR dashboards.
  • Own your hosting. The javagitsshserver gives us a place to host repositories that does not depend on GitHub at all.
  • Agent-ready. A swarm can clone/push to self-hosted repos and open/merge PRs through the proxy under scoped W3Wallet capabilities, rather than ambient credentials.

Why the GitHub proxy is a control point

GithubProxy is not a convenience wrapper — it exists to be the single point through which all GitHub access flows, for four reasons that matter especially once agents are in the loop:

  1. Credential containment. GitHub credentials live only inside the proxy; consumers never hold a token, so raw credentials cannot leak from a client, a log, or a sandboxed agent.
  2. Fine-grained permissions to limit blast radius. A central chokepoint is where each caller is scoped to only the repositories and operations it needs — so a single misbehaving or compromised agent in a swarm cannot reach beyond its grant. The chokepoint also denies the moves an agent reaches for to escape its bounds: the GithubProxy plan forbids, by default, mutating a repository's CI configuration or required checks (so CI cannot be bypassed to force-merge an otherwise-unmergeable change) and opening a PR against any branch but the default (always a mistake), each unlocked only by an explicit, single-conversation step-up grant the agent cannot mint for itself.
  3. Rate-limit enforcement across users. All GitHub traffic is tracked and fairly allocated against GitHub's API limits centrally, instead of every consumer independently exhausting a shared budget.
  4. W3Wallet compatibility. The proxy's API is built to integrate with W3Wallet for billing and permission management, so GitHub access is governed by the same capability/quota model as the rest of the platform.

Plan / roadmap

These are proposed and need sharpening before work starts.

  • [ ] A unified "Git" story. Decide how the four sub-areas present as one capability — e.g. a single entry point and consistent docs — versus four independent services.
  • [ ] W3Wallet-gated access. Put GithubProxy mutations and self-hosted-repo push behind W3Wallet capabilities, so who-can-do-what is explicit and auditable (critical before agents use it). For the proxy this is fleshed out in the dedicated GithubProxy plan: users register their own GitHub keys and hand out add / view / use / remove capabilities over them, so a wallet can be granted permission to use a key without ever being able to view it.
  • [ ] Full GitHub coverage behind the gate. Target complete gh/GitHub-API coverage — common operations typed plus a gated gh api-style passthrough for the rest — so the drop-in gh is genuinely complete. Safety comes from per-grant attenuation and the deny-by-default guardrails (every operation, passthrough included, runs the same forbidden-class classifier), not from keeping the surface small; the GithubProxy plan works this out.
  • [ ] Harden the self-hosted server. Per-repo access control, key management, and backup/restore for javagitsshserver; confirm the lightweight git-javagitsshserver implementation is the maintained one and reconcile the two.
  • [ ] Watchman → proxy loop. Make it turnkey to react to a GithubWatchman invalidation by calling GithubProxy (the change-detected → act pattern), documented as a reusable recipe.
  • [ ] End-to-end tests per the testing standards: a real self-hosted server handling clone/push, and proxy/watchman flows against a controlled fixture rather than live GitHub.

Open questions

  • Two SSH-server implementations. git-javagitsshserver and javagitsshserver overlap heavily — is one the library and the other the deployment, or should they converge into a single project?
  • GitHub vs. self-hosted. When should a repository live on GitHub (reached via the proxy) vs. on our own SSH host? This workstream should offer a "when to use which" guide.
  • Credential model. Where do the proxy's GitHub tokens and the SSH server's host/authorized keys live, how are they rotated, and how does that line up with W3Wallet? The GithubProxy plan answers this for the proxy side — per-owner registered keys held wallet-side (self-hosted first), use-without-view grants, and capability-gated rotation. The SSH-server side should follow the same register → use-without-view pattern as its own authority home (different secret, git-over-SSH rather than the REST API) — still to be worked out here.

Graduation

GithubWatchman and (with the companion PR) GithubProxy have Documentation Repository project pages; the SSH servers do not yet. This workstream graduates when the four parts are presented as one coherent, W3Wallet-gated Git capability with the self-hosted server hardened and a documented change-detected → act loop; at that point give the SSH servers a project page.