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-client
It is imported as gitd. Up to 0.13.0 it was published as gitd; from 0.14.0 it is
gitd-client, the name every gitd client has.
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, *, requested_by, pull_request, provenance, sandbox, update) |
Its commits pushed to a new branch, or with update an earlier publish's branch moved forward; its pull request opened or updated |
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 |
from gitd import PullRequestOptions
published = gitd.publish(
workspace.path, "agents/fix-login", update=True,
pull_request=PullRequestOptions(open=True, submodules=True, title="Fix the login", body="…"),
)
print(published.pull_request.url, published.pull_request.updated)
for submodule in published.submodule_pull_requests: # merged first, with a merge commit
print(submodule.path, submodule.pull_request or submodule.refused)
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, macOS and Windows. Apache-2.0.
Metadata
Release files for gitd-client 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gitd_client-0.14.0.tar.gz | 26.2 kB | With provenance | Details for gitd_client-0.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gitd_client-0.14.0-py3-none-any.whl | Python 3 | none | any | Details for gitd_client-0.14.0-py3-none-any.whl |
Total release size: 58.7 kB
Release files / gitd_client-0.14.0.tar.gz
| Download URL | gitd_client-0.14.0.tar.gz |
|---|---|
| Size | 26.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
98ab14ab4cf2ef29d4bad56434152e2671c6c3909d8a258441c85ef25077020d
|
|
BLAKE2b-256 checksum How to use checksums |
d246e1c7ee41e541eff046ceac3d260a475cdb8f1911d17f9d0628c824f7af42
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / gitd_client-0.14.0-py3-none-any.whl
| Download URL | gitd_client-0.14.0-py3-none-any.whl |
|---|---|
| Size | 32.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18ed6cdf4d22495d5f1162b61d0697d3377d5784c5c40b094125dfc88dafb3bd
|
|
BLAKE2b-256 checksum How to use checksums |
f85b030c91eebed2c9ef65d99f9993f4fbffc0ec097741c217635f9acc8a104e
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for gitd-client 0.14.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gitd_client-0.14.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.