gitd for Python

A client for gitd: instant, secretless git checkouts for agent sandboxes. Your agents work in their own copy and publish a branch; they never see your token.

pip install gitd

from gitd import Gitd, GitdError

with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
    print(workspace.path, workspace.commit, workspace.strategy)

    # … the agent works in workspace.path with plain git, and commits …

    published = gitd.publish(workspace.path, "agents/fix-login")
    gitd.remove(workspace.path)

No call takes a credential: gitd reads and publishes with the ones it keeps.

Method	What it does
`prepare(url, path, *, branch, commit, submodules, full_history, strategy, on_progress)`	A workspace of a repository at a path under gitd's roots
`update(path, *, branch, submodules, on_progress)`	To the tip of its branch, or of the branch given
`checkout(path, commit, *, submodules, on_progress)`	To a commit, as a rollback does
`describe(path)`	Its repository, commit, branch, uncommitted changes and submodules
`publish(path, branch)`	Its commits pushed to a new branch
`remove(path)`	Deleted; its pool stays
`probe(url)`	Whether it can be read, its default branch and branches
`info()`	Which gitd answers, and how it makes workspaces here and why
`audit(*, since, url, limit)`	Every publish, done or refused, newest first

A refusal raises GitdError, with reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BRANCH_REFUSED, BUSY, …) and said, what git said. Decide from the reason, never from the message.

examples/agent.py is an agent's whole round trip.

Layout

Path	What it is
`src/gitd/client.py`	`Gitd`, the client
`src/gitd/models.py`	What gitd answers, as dataclasses
`src/gitd/errors.py`	`GitdError`
`src/gitd/timestamps.py`	Between the contract's timestamps and `datetime`
`src/gitd/connection.py`	The channel to the socket, and how calls are made
`src/gitd/methods.py`	The gitd methods called, by their gRPC path
`src/gitd/messages.py`	The messages of the contract the client uses
`src/gitd/contract.py`	Reads the contract at run time, with protobuf's public API
`src/gitd/contract.json`	The contract, built from `proto/gitd/v1/gitd.proto` by `make generate`

No code is generated: the client reads gitd's contract when it starts.

Python 3.11 or later, on Linux. Apache-2.0.

Metadata

Release files for gitd 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gitd 0.7.0
File	Size	Uploaded
gitd-0.7.0.tar.gz	12.0 kB	Oct 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gitd 0.7.0
File	Interpreter	ABI	Platform	Reset
gitd-0.7.0-py3-none-any.whl 14.1 kB Oct 17, 2026	Python 3	none	any	Details

Total release size: 26.1 kB

Release files / gitd-0.7.0.tar.gz

Download URL	gitd-0.7.0.tar.gz
Size	12.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`8b515942ce5d50c128f4e799002b3665d998f8849612c95de6d394ab16d191bf`
BLAKE2b-256 checksum How to use checksums	`076fc96354a8bbc6165eeb72385cb8feded4447ddff429a893b1ebd1dc7d7177`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dooservice/gitd
Publishing commit: github.com/dooservice/gitd/tree/5def268b948dacf7507a447baba585eb04935fcd

Workflow

Publishing configuration: github.com/dooservice/gitd/blob/5def268b948dacf7507a447baba585eb04935fcd/.github/workflows/sdks.yml
Publishing logs: github.com/dooservice/gitd/actions/runs/39020277055/attempts/3

Artifact

Subject: gitd-0.7.0.tar.gz
SHA-256 checksum: 8b515942ce5d50c128f4e799002b3665d998f8849612c95de6d394ab16d191bf Verifying attestations

Release files / gitd-0.7.0-py3-none-any.whl

Download URL	gitd-0.7.0-py3-none-any.whl
Size	14.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`606c9dc9ff496cb84c40c1823e51a2304058db5af04b1eec527de006f25ebdbd`
BLAKE2b-256 checksum How to use checksums	`93c6a234175dfe73ac901a854e764c62771c56bc2c13663bcdea92a20699d9dd`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dooservice/gitd
Publishing commit: github.com/dooservice/gitd/tree/5def268b948dacf7507a447baba585eb04935fcd

Workflow

Publishing configuration: github.com/dooservice/gitd/blob/5def268b948dacf7507a447baba585eb04935fcd/.github/workflows/sdks.yml
Publishing logs: github.com/dooservice/gitd/actions/runs/39020277055/attempts/3

Artifact

Subject: gitd-0.7.0-py3-none-any.whl
SHA-256 checksum: 606c9dc9ff496cb84c40c1823e51a2304058db5af04b1eec527de006f25ebdbd Verifying attestations