backend

BitIssues Backend

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

Get Started · Report Bug · Request Feature

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
• 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)
        └── 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.

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.

Development Commands

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
• 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
• Alpine.js
• Tailwind CSS
• Swaggo
• GoReleaser
• Best-README-Template

(back to top)