git-bug: a distributed bug tracker stored in your git repository

What git-bug replaces, and for whom

A hosted issue tracker is a second system with its own accounts, its own availability and its own export format. git-bug removes that second system. The README describes it as fully embedded in git: you only need your git repository to have a bug tracker. Bugs are not files committed into your project tree; the project states that no files are added in your project, which is the detail that matters if you were worried about issue data showing up in a diff.

The target user is a team or a solo developer who already collaborates through a git remote and wants issues to move over that same transport. The README frames the benefits as distributed collaboration through your normal git remote, offline work, and a full local backup if a hosted service goes down or goes bad. That last point is the strongest argument for the design: the data is yours because it never left the repository.

It is a weaker fit for open source projects that accept bug reports from strangers. The README is explicit that the web UI is not up to speed for the public portal workflow and that contributions there are welcome.

How bugs are stored: refs, DAG entities and a cache

The mechanism is visible in the repository layout and the Makefile. Bug data lives under refs/bugs/, and identities live under refs/identities/. The maintenance targets confirm this: clean-local-bugs deletes refs/bugs/ and refs/remotes/origin/bugs/, and clean-local-identities does the same for refs/identities/. So an issue is a git ref, not a file, and it is fetched and pushed like any other ref.

The README points to a data model document and an internal architecture document, and says the on-disk format is formally specified in the git-bug spec, covering the DAG entity format, identities and the bug entity. That spec is the piece to read if you want to write another implementation or a tool that reads git-bug data directly. The project also ships entity/dag/example_test.go as a worked example of building your own distributed data structure in git.

Reads are cached rather than recomputed. The Makefile removes .git/git-bug/bug-cache and .git/git-bug/identity-cache, which tells you the cache is local and disposable: deleting it costs time, not data. The CLI and the web UI sit on top of the same backend. The web UI is packed into the same Go binary and served by a local HTTP server, and it talks to the backend through a GraphQL API whose schema is published in the repository.

Installing git-bug and filing your first bug

The README does not list install commands. It points to INSTALLATION.md for the complete guide, including how to build from source and verify your install. Start there rather than guessing at a package manager.

If you build from source, the Makefile shows the expected flow. The build target first builds the web UI, then runs go generate and compiles with the webui build tag:

make build

There is also a make install target that runs the same steps and installs the binary. Note that the webui/dist target runs pnpm install and pnpm run build inside webui/, so a source build needs the frontend toolchain, not just Go.

Once the binary is on your PATH, create an identity. the README lists this as the first step:

git bug user new

Then file a bug. The README states that your favorite editor opens so you can write a title and a message:

git bug add

List what you have, and filter with a query. The README gives this example:

git bug ls "status:open sort:edit"

To share the bug, push it to a remote and pull updates the same way:

git bug push [<remote>]
git bug pull [<remote>]

Brackets around the remote mean it is optional, matching the README. If you prefer a browser, git bug webui launches a local server with issue browsing, search, comments and a code browser.

Where git-bug gets in the way

The first constraint is participation. A bug is only readable by someone who has git-bug installed or a tool that understands the on-disk format. Your repository is still a normal git repository, but an unfamiliar reader who clones it sees refs they cannot interpret. The published spec is the escape hatch, and it exists precisely because the project expects other implementations.

Second, the public-facing story is unfinished. The README labels the web UI workflow as WIP and states that the web UI aims to accept external OAuth authentication and act as a public portal, but is not up to speed for that yet. If your process is "post the URL and let anyone file an issue", git-bug is the wrong tool today.

Third, bridges are asymmetric by design. The README directs you to a feature matrix to see what each bridge supports, which implies that GitHub, GitLab, Jira and Launchpad are not interchangeable. Import and export through a bridge is a translation layer, and translation layers lose fields. Check the matrix for the specific tracker before you plan a migration.

Fourth, the CLI is the real interface. The interactive terminal UI (git bug termui) and the web UI are conveniences on top of it, and the README describes the web UI as part of the same binary, so a build without the webui tag changes what you get.

Bridges versus a native git remote

git-bug offers two collaboration models, and they are genuinely different. In the native workflow, everyone uses git-bug and syncs with git bug push and git bug pull over an ordinary git remote. There is no translation and no external service in the loop.

In the bridge workflow, git-bug acts as a local remote interface to another tracker. You configure a bridge, then sync with git bug bridge pull and git bug bridge push. The README gives both an interactive path and a manual one:

git bug bridge new \
    --name=<bridge> \
    --target=github \
    --url=https://github.com/git-bug/git-bug \
    --login=<login> \
    --token=<token>

That is the honest comparison point against a hosted tracker. A hosted tracker is the source of truth and everyone sees the same thing. With git-bug bridges, the local repository is your working copy and the hosted tracker is a peer you reconcile with. That is more flexible and it is also more work: conflicts and one-way fields become your problem, which is why the feature matrix matters more than the command list.

Licence and the cost of keeping up

git-bug is GPL-3.0. If you only run the binary and use the CLI, that is the normal case and the licence is not a practical concern. If you link the code into your own product or ship a modified binary, the copyleft terms apply, and this article is not legal advice; read the LICENSE file in the repository.

The maintenance picture is straightforward from the repository data. The last push to trunk was on 2026-11-01, so the project is being worked on. The most recent release is v0.11.0 from 2026-09-22; before it came v0.10.1 (2025-05-19) and v0.10.0 (2025-05-18).

Upgrade cost is low for the CLI because the on-disk format is formally specified in the git-bug spec. It is higher if you build from source: the Makefile pulls in a pnpm frontend build, go generate, and a build tag, so your toolchain has to track both Go and Node dependencies. The go.mod pins Go 1.26.0 and a long dependency list including go-git, bleve, gqlgen and the GitHub and GitLab API clients. Expect a periodic dependency refresh, and note the secure target, which runs go tool govulncheck ./... if you want to check for known vulnerabilities yourself.

Choosing between git-bug and a hosted tracker

The decision comes down to who has to read the issues. If the answer is "the people who already clone this repository", git-bug is a good fit and the offline behaviour is a real benefit on a plane or a bad connection. If the answer includes customers, external contributors or anyone who will not install a Go binary, a hosted tracker wins on reach, and git-bug's own README concedes that the public portal workflow is not ready.

There is also a middle path worth considering. Use git-bug locally as your interface and keep a hosted tracker as the public face through a bridge. The README describes exactly this: git-bug as your personal local remote interface, syncing with git bug bridge pull and git bug bridge push. That gives you terminal-speed triage without asking anyone else to change tools. It also means the hosted tracker remains the place where non-technical users file reports, which is where the model breaks down.

Editorial conclusion

Adopt git-bug if your team already pushes code to a shared git remote and you want issues to live in the same place, offline and without a separate service. Skip it if you need a public portal where outside users file bugs: the README marks the web UI workflow as WIP, and the web UI is not ready to accept external OAuth authentication. Before committing, verify the bridge feature matrix for the tracker you plan to sync with, and confirm that every collaborator can install the binary, because bugs are only visible to people who have git-bug or a tool that reads the on-disk format.

Frequently asked questions

Official sources

1. git-bug/git-bug on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases