Time tracking for teams that live in GitHub.
Developers log hours with slash commands in issue comments. Billbird stores the entries, attributes them to clients, and gets out of the way.
A developer finishes work on an issue. They comment:
/log 2h
Billbird's bot replies:
Logged 2h for @developer (entry #1)
That's it. The time is recorded, linked to the issue, and visible to admins. No app to open, no tab to switch to, no form to fill out.
Need to fix a mistake? Comment /correct 3h. Need to remove it entirely? Comment /delete. Every change is tracked, nothing is ever lost.
| Command | Example | What it does |
|---|---|---|
/log <duration> [description] |
/log 1h30m Code review |
Log time on the current issue |
/correct <duration> [description] |
/correct 2h |
Replace your last entry on this issue |
/delete |
/delete |
Remove your last entry on this issue |
/plan <duration> [description] |
/plan 8h |
Forecast effort for this issue |
/unplan |
/unplan |
Remove the active plan from this issue |
Durations support hours (2h), minutes (45m), or both (1h30m). Plans and log entries live in separate tables: /log records actuals, /plan records forecasts. The admin panel and the API expose a plan-vs-actual view that compares the two.
Billbird is a GitHub App that listens to issue comment webhooks. When it sees a slash command, it:
- Parses the command and duration
- Checks the issue's labels to auto-attribute a client (if configured)
- Stores the time entry in Postgres
- Posts a confirmation comment on the issue
Corrections create a new entry that supersedes the old one. Deletes mark entries as deleted. Nothing is ever physically removed from the database --- the issue thread is the audit log.
Billbird is one instance per organisation: each organisation gets its own Postgres database, its own GitHub App, and its own secret store. Multi-tenant SaaS hosting is explicitly out of scope. See docs/self-hosting.md for the operator playbook.
git clone https://github.com/mwesterweel/billbird.git
cd billbird
cp env.example .env # set BASE_URL and ALLOWED_ORGS
docker compose run --rm --service-ports app billbird init
# one-click GitHub App registration
docker compose up -d # then install the App in your browser
docker compose exec app billbird doctor # sanity checkSee docs/setup.md for the full automated path or the manual fallback.
Billbird is a GitHub App and integrates only with GitHub today. The Postgres schema, command parser, admin UI, and REST API are platform-agnostic, but the webhook ingestion and authentication layers are GitHub-specific (App installations, manifest flow, HMAC signature, org-membership endpoint).
GitLab and Forgejo are not currently supported. Porting Billbird to either is real work — see docs/architecture.md#platform-support for what would need to change and an honest cost estimate. The path is open, but no roadmap commitment until there's concrete demand.
- Setup guide --- GitHub App registration, configuration, deployment
- Commands reference --- Slash command syntax and behavior
- Labels --- Label conventions (strippenkaart, WBSO, type, internal) and how to query them
- Dev-time hook --- Optional pre-commit hook that adds a
Time:footer per commit - API tokens --- Bearer tokens for non-browser API consumers
- Client attribution --- Mapping GitHub labels to clients
- Corrections and deletions --- How the correction chain works
- Architecture --- System design and API-first approach
- Configuration reference --- All environment variables
- Self-hosting --- Docker Compose and Kubernetes deployment
- Contributing --- Development setup and guidelines