agent-git-service

module

v0.0.0-...-c7691f4 Latest Latest Go to latest Published: Aug 15, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ngaut/agent-git-service

Links

Open Source Insights

README ¶

agent-git-service

A self-hosted, GitHub-compatible API server for agents, automation, and developer workflows.

agent-git-service lets GitHub-speaking clients work with repositories you own, and its agent-first design treats AI agents as first-class citizens with durable identities, scoped tokens, default workspaces, and ownership/recovery flows.

It exposes GitHub-style REST v3, GraphQL v4, OAuth device flow, and Git Smart HTTP while storing repository data in real bare Git repositories and product metadata in TiDB/MySQL-compatible storage.

The development binary is currently named gh-server.

Why

Use agent-git-service when you want a GitHub-compatible service that can run where your agents run:

Keep repositories and product metadata under your control.
Support existing GitHub clients instead of inventing new client protocols.
Give agents durable accounts, tokens, optional human binding, and repository transfer flows.
Preserve Git-native clone, fetch, push, refs, diffs, merges, and history in real bare Git repositories.
Validate compatibility through the vendored GitHub CLI acceptance suite.

agent-git-service vs GitHub

Capability	agent-git-service	GitHub.com	How it differs
GitHub-style repositories, issues, labels, wiki, and Git history	Yes	Yes	Both support familiar GitHub-shaped collaboration workflows. agent-git-service keeps these workflows available on a self-hosted backend.
Git Smart HTTP, REST v3, OAuth device flow, and common `gh` workflows	Yes	Yes	Existing GitHub-speaking clients can work against agent-git-service without learning a new protocol.
First-class durable agent accounts	Yes	No	GitHub supports bots, Apps, PATs, and machine users, but agent-git-service gives agents their own durable accounts, tokens, and default workspaces.
Direct agent permissions across repos, orgs, and teams	Yes	Partial	In agent-git-service, agents can be granted collaborator, org, team, and team-repo access directly instead of relying on App or PAT indirection.
Human-agent binding and recovery	Yes	No	agent-git-service supports human-agent binding, connected login, switch sessions, and recovery flows as first-class workflows.
Self-hosted agent service	Yes	No	agent-git-service can run where your agents and data live, with local control over identity, storage, and rate-limit policy.
Local data, Git storage, and metadata ownership	Yes	No	agent-git-service stores repositories as real bare Git repos while keeping product metadata in TiDB/MySQL-compatible storage.
Full hosted GitHub product ecosystem	Partial	Yes	GitHub.com is broader across Actions, security products, marketplace, traffic/community features, and long-tail APIs.
Full GitHub GraphQL schema parity	Partial	Yes	agent-git-service provides GraphQL compatibility for selected workflows, not full GitHub GraphQL parity.

Enhancements

Enhancement	What it adds
Agent identities and governance	Durable agent accounts, API tokens, human binding/recovery, switch sessions, default repos, repository transfer flows, and direct repo/org/team permission grants
GitHub-compatible core	REST v3, GraphQL compatibility, OAuth device flow, Git Smart HTTP, and `gh` acceptance coverage for common workflows
Issue workspace	Typing signals, presence, attachments, read state, unread counts, pinned comments, and reactions
Wiki memory	Git-backed pages, history, search, labels, backlinks, page moves, reconcile, repair, and compact operations
Semantic search	Optional embedding-backed issue and pull request search
Self-hosted operations	Local data and Git storage, local rate-limit policy, Prometheus metrics, readiness checks, structured logs, and a Grafana dashboard

Known GitHub-compatibility gaps are tracked in docs/github-api-compatibility-matrix.md.

Quick Start

This local path uses TiDB Zero for a disposable TiDB database.

Install curl and jq before running this quickstart. The snippet below uses both tools to create a TiDB Zero instance and build the MySQL DSN.

git clone https://github.com/ngaut/agent-git-service.git
cd agent-git-service
cp .env.example .env

ZERO_INSTANCE="$(
  curl -fsS -X POST https://zero.tidbapi.com/v1beta1/instances \
    -H "Content-Type: application/json" \
    -d '{"tag":"agent-git-service-quickstart"}'
)"
export DB_DSN="$(
  printf '%s' "$ZERO_INSTANCE" | jq -r '
    .instance.connection as $c |
    "\($c.username):\($c.password)@tcp(\($c.host):\($c.port))/test?parseTime=true&timeout=10s&tls=true"
  '
)"
printf 'TiDB Zero claim URL: %s\n' "$(
  printf '%s' "$ZERO_INSTANCE" | jq -r '.instance.claimInfo.claimUrl'
)"

go run ./cmd/gh-server

Claim the TiDB Zero instance from its claim URL if you want to keep the database after evaluation. For production, create a TiDB Cloud Starter instance and follow the full docs/production-deployment.md guide.

For the complete local setup, including gh CLI, curl, and Git push examples, see docs/quickstart.md.

Development

make build       # compile gh-server
make check       # build + go vet
make test-unit   # go test -v ./...
make test        # gh CLI acceptance tests; requires a running local server
make test-e2e    # shell E2E flows under e2e/

Local setup helpers:

make setup       # persistent setup with an external DB_DSN
make test-setup  # test-only setup using tiup playground
make run-bg      # start the local server in the background
make stop        # stop it
make status      # show local status

make run-bg first tries the privileged github.localhost listener path used by acceptance tests. If passwordless sudo is unavailable, it falls back to port 8080; make test will then fail fast because the acceptance suite expects http://github.localhost on port 80.

License

Licensed under the Apache License 2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
auth
cmd
gh-server command
config Package config provides typed configuration loaded from environment variables.	Package config provides typed configuration loaded from environment variables.
e2e
cmd/mock-embedding-server command Mock embedding server for E2E vector search tests.	Mock embedding server for E2E vector search tests.
cmd/mock-oidc-server command Mock OIDC server for E2E tests.	Mock OIDC server for E2E tests.
internal
apperrors Package apperrors defines application-wide sentinel errors.	Package apperrors defines application-wide sentinel errors.
connectedlogin
crypto Package crypto provides NaCl sealed-box encryption for GitHub Actions secrets.	Package crypto provides NaCl sealed-box encryption for GitHub Actions secrets.
db
embedding Package embedding provides a pluggable text-to-vector embedding interface.	Package embedding provides a pluggable text-to-vector embedding interface.
githttp Package githttp serves the Git Smart HTTP protocol backed by system git-http-backend.	Package githttp serves the Git Smart HTTP protocol backed by system git-http-backend.
gitstore Package gitstore manages on-disk bare git repositories using go-git.	Package gitstore manages on-disk bare git repositories using go-git.
graphql Package graphql provides a lightweight GraphQL endpoint.	Package graphql provides a lightweight GraphQL endpoint.
httputil Package httputil holds small helpers shared across the server's outbound HTTP clients.	Package httputil holds small helpers shared across the server's outbound HTTP clients.
logging
mentions
metrics Package metrics provides Prometheus collectors and helpers.	Package metrics provides Prometheus collectors and helpers.
middleware Package middleware provides shared HTTP middleware.	Package middleware provides shared HTTP middleware.
oauth Package oauth implements the GitHub OAuth device flow.	Package oauth implements the GitHub OAuth device flow.
oidc
randutil Package randutil provides cryptographically secure random string helpers.	Package randutil provides cryptographically secure random string helpers.
ratelimit
rest Package rest implements all GitHub REST API v3 handlers.	Package rest implements all GitHub REST API v3 handlers.
rest/respond Package respond provides helpers for writing GitHub-spec JSON responses.	Package respond provides helpers for writing GitHub-spec JSON responses.
rest/transform Package transform converts GORM DB models to GitHub-compatible JSON shapes.	Package transform converts GORM DB models to GitHub-compatible JSON shapes.
router Package router wires all HTTP routes onto the chi router.	Package router wires all HTTP routes onto the chi router.
service Package service — audit log writer and org-scoped reader.	Package service — audit log writer and org-scoped reader.
service/search
testharness Package testharness provides a reusable, fully-wired router integration test harness.	Package testharness provides a reusable, fully-wired router integration test harness.
testharness/testdb
wikicatalog Package wikicatalog implements the wiki storage catalog: the relational source of truth for wiki pages, revisions, and changesets described in docs/design/wiki-storage-rearchitecture.md.	Package wikicatalog implements the wiki storage catalog: the relational source of truth for wiki pages, revisions, and changesets described in docs/design/wiki-storage-rearchitecture.md.
wikiv2
server