BitIssues Backend

A lightweight, self-hosted task tracker replacing Bitbucket Issues
Explore the docs »

Get Started · Report Bug · Request Feature

Table of Contents

• Table of Contents
• About The Project
  • Features
  • Architecture
  • Built With
• Getting Started
  • Download
  • Prerequisites
  • Build from Source
• Usage
  • CLI Commands
  • API Overview
  • Configuration
  • Development Commands
  • Deployment
• Roadmap
• Contributing
• License
• Contact
• Acknowledgments

About The Project

Bitbucket Issues sunsets in August 2026. BitIssues is a self-hosted replacement for teams who need simple task tracking without the overhead of full-featured tools like Jira.

Here's why BitIssues exists:

• Drop-in migration — import your existing Bitbucket Issues JSON export with a single CLI command
• Lightweight — single Go binary with an embedded SPA frontend, no heavy infrastructure
• Self-hosted — full control over your data, deploy anywhere (bare metal, Docker, Kubernetes)

(back to top)

Features

• Projects — create and manage projects with auto-generated slug-based routing
• Tasks — full lifecycle with priority (trivial → blocker), status (new → closed), kind (bug, enhancement, task, proposal), assignees, and due dates
• Comments — per-task discussion with markdown support
• File Attachments — two-phase upload via S3 presigned URLs (client uploads directly to storage, bypassing the server)
• JWT Authentication — HS256 tokens with Argon2id password hashing
• WebAuthn/Passkey Authentication — passwordless login via platform authenticators (fingerprint, Face ID, security keys)
• Role-Based Access — admin and user roles with pending activation flow
• Rich Filtering & Sorting — tasks filterable by project, author, assignee, status, priority, date range
• Dashboard Queries — quick access to tasks assigned to or created by the current user
• Swagger/OpenAPI — auto-generated API docs at /api/v1/docs

(back to top)

Architecture

The project follows a clean/layered architecture organized as Uber Fx modules:

main.go
  └── app.go
        ├── serve command       # HTTP server
        │     └── Fx container
        │           ├── Core (logger, db, storage, validator, health)
        │           ├── Server (handlers, middlewares, routes, swagger)
        │           └── Domains (users, projects, tasks, comments, attachments, webauthn)
        └── import command      # Bitbucket import CLI

Each domain module follows the same layout:

• domain.go — entities, value objects, enums, validation
• models.go — ORM database models with domain converters
• repository.go — data access layer
• service.go — business logic
• module.go — Fx provider wiring
• errors.go — domain-specific errors

The HTTP layer lives in internal/server/ with separate handler/DTO files per domain and a shared JWT middleware for auth enforcement.

Attachment upload flow:

Client                  Server                  S3 Storage
  │                       │                        │
  │── POST /attachments ──▶  Create pending record │
  │                       │── Generate presigned   │
  │                       │   PUT URL              │
  │◀── Presigned URL ─────│                        │
  │── PUT file ───────────┼──────────────────────▶│
  │── PUT /confirm ──────▶│  Set status=uploaded   │
  │                       │── Delete from S3       │
  │── DELETE ────────────▶│  Soft-delete record    │

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

Download

Get the latest pre-built binary or Docker image:

Option 1 — Binary (GitHub Releases)

# Download the latest release for your platform
curl -LO https://github.com/bit-issues/backend/releases/latest/download/backend_Linux_x86_64.tar.gz
tar xzf backend_Linux_x86_64.tar.gz
./backend serve

Or download manually from the Releases page. Binaries are available for Linux, macOS, and Windows.

Option 2 — Docker (GHCR)

docker pull ghcr.io/bit-issues/backend:latest

docker run -d \
  -p 3000:3000 \
  -e DATABASE__URL="mariadb://..." \
  -e STORAGE__URL="s3://..." \
  ghcr.io/bit-issues/backend:latest

Prerequisites

• MySQL 8+ or MariaDB 10.5+
• S3-compatible storage (use MinIO for local development)

Build from Source

For development or custom builds:

1. Clone the repo

   git clone https://github.com/bit-issues/backend.git
   cd backend

2. Configure environment

   cp .env.example .env
   # Edit .env with your database and S3 credentials

3. Install Go dependencies

   make deps

4. Generate Swagger documentation

   make gen

5. Start the development server

   make air

   Database migrations run automatically on startup.

(back to top)

Usage

CLI Commands

# Start HTTP server (default)
backend serve

# Import Bitbucket Issues JSON export
backend import --project=<slug> --file=<path> --default-user=<id> [--dry-run]

# Show version
backend --version

The import command maps Bitbucket issues and comments into the BitIssues schema. Use --dry-run to preview without writing.

API Overview

All endpoints are under /api/v1. Full documentation is available via Swagger UI at /api/v1/docs.

Area	Base Path	Auth
Auth	/auth	Public (login, register)
Users	/users	JWT (admin for management)
Projects	/projects	JWT
Tasks	/tasks	JWT
Comments	/tasks/:taskId/comments	JWT
Attachments	/tasks/:taskId/attachments	JWT
Passkeys	/auth/passkey	Public (login) / JWT (manage)
Docs	/docs	Public

A complete API reference with request/response examples is available in requests.http.

Configuration

Configuration is loaded from environment variables with optional YAML override via CONFIG_PATH.

Variable	Default	Description
DATABASE__URL	mariadb://bit-issues:...	Database connection string
JWT__SECRET	secret	JWT signing key
JWT__ACCESS_TTL	15m	Access token lifetime
STORAGE__URL	s3://bucket/prefix?...	S3 storage URL
STORAGE__LINKS_TTL	15m	Presigned URL lifetime
ATTACHMENTS__MAX_SIZE	10485760	Max file size in bytes (10 MB)
HTTP__ADDRESS	127.0.0.1:3000	Server listen address
AWS_ACCESS_KEY_ID	—	S3 access key
AWS_SECRET_ACCESS_KEY	—	S3 secret key
AWS_REGION	—	S3 region
WEBAUTHN__RP_DISPLAY_NAME	BitIssues	Display name shown during registration
WEBAUTHN__RP_ID	localhost	Relying Party ID (domain)
WEBAUTHN__RP_ORIGINS	["http://localhost:5173"]	Allowed origins JSON array

Development Commands

Command	Description
make fmt	Format code via golangci-lint
make lint	Run linter
make test	Run tests with race detector and coverage
make coverage	Generate HTML coverage report
make benchmark	Run benchmarks
make build	Compile binary to bin/
make air	Start dev server with live reload
make gen	Run go generate (Swagger docs)
make deps	Download Go module dependencies
make clean	Remove build artifacts

Deployment

Pre-built multi-arch Docker images are published to GHCR (ghcr.io/bit-issues/backend) and binaries to GitHub Releases on every version tag.

• Docker — docker pull ghcr.io/bit-issues/backend:latest (linux/amd64, linux/arm64)
• Binary — download platform-specific tarballs from the Releases page
• CI/CD — GitHub Actions: lint + test (push/PR), release + publish (tag v*), PR snapshot builds

(back to top)

Roadmap

• Bitbucket Issues JSON import
• JWT authentication with Argon2id
• WebAuthn/passkey authentication
• File attachments via S3 presigned URLs
• Email notifications
• Webhook integration
• Multi-language support
• Kanban board view

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/bit-issues/backend

(back to top)

Acknowledgments

• Fiber
• Uber Fx
• uptrace/bun
• pressly/goose
• MinIO
• Svelte
• Tailwind CSS
• Swaggo
• GoReleaser
• Best-README-Template

(back to top)