git-bug

Last reviewed Aug 26, 2026 · 745 words

git-bug is the one issue tracker on this site you do not host. Issues are Git objects stored under their own refs, they travel with git push and git pull, and the "server" is whatever remote you already have: a Forgejo box, GitHub, or a bare repository on a NAS. There is no database, no web service to keep alive, and the whole thing is a 64 MB Go binary. That makes it either exactly what you wanted or entirely the wrong shape, and the deciding question is how many people need to see the tickets without cloning the code.

Issues live in refs, not in your working tree

Run git bug in a repository and it writes to refs/bugs/ and refs/identities/, never to tracked files. Your source tree stays clean, git log stays clean, and a plain git clone will not fetch the issues unless you ask for them. Each issue is an append-only log of operations (created, commented, labelled, closed), which is what lets two people edit the same issue offline and merge without conflicts. The design is unconventional, as the catalogue says, but it is also why the tool has held 10,015 stars since 2018 without needing a hosted product to survive.

A working day with it

Install the binary from the GitHub releases page or your package manager, then in a repository:

git bug user create              # once, sets your identity
git bug add                      # opens your editor for a new issue
git bug ls                       # list open issues
git bug termui                   # full-screen terminal UI
git bug webui                    # local web UI in your browser
git bug push && git bug pull     # sync issue refs with the remote

One caution: the project reorganised its subcommand layout in recent releases, so treat git bug --help as the authority over any blog post, including this one. The web UI is a local process on your own machine with no authentication, and that is the intended model; it is not something to put behind a public hostname.

The bridge is both the migration path and the escape hatch

git bug bridge configure connects a repository to GitHub, GitLab or Jira. A bridge pull imports the remote issues into local refs, which gives you a complete offline mirror of a project's tracker that you can search on a plane. A bridge push sends your local changes back. Two real uses fall out of this. The first is working on a GitHub project without a connection. The second is insurance: if you migrate from GitHub to a self-hosted forge, the issues that git-bug has already pulled come with the repository as ordinary Git data, no export tooling required.

What you give up

Almost everything that makes a hosted tracker a collaboration product. There are no email notifications, no cross-repository views, no boards, no milestones worth the name, and no permission model beyond "can push to the remote": anyone with write access to the repository can edit or close any issue. Non-developers cannot participate without a Git client. For a team that already lives in Jira or GitHub Issues with product managers commenting, git-bug will feel like a downgrade, because for that audience it is one.

Who it genuinely fits

Solo developers who want issues to survive every forge change they will ever make. Small teams of 2 to 4 engineers who already review each other's work over Git and want tickets in the same place. Air-gapped or intermittently connected environments where a web tracker is unreachable half the time. And anyone who uses Gitea or Forgejo purely as a Git remote and finds their built-in trackers more than they need. The pairing that works best in practice is git-bug for engineering tickets plus the forge's own tracker for anything a non-engineer must see.

What I'd do

If you are one person or a tiny team, install git-bug in your main repositories today, pull your existing GitHub issues through the bridge once, and use termui as the daily interface. Keep pushing to the forge you already have. If anyone outside engineering needs to file or read a ticket, stop here and use the forge's built-in tracker instead; git-bug is a tool for people who think in Git, and it is a very good one for exactly them.