GitBucket: a Scala Git platform that installs with one command

The packaging decision that defines the project

GitBucket's most consequential design choice is not architectural, it is distributional. The whole server ships as a single executable war file that you run with a Java command. That constraint explains nearly everything else about the project: why installation is a two step process rather than a service manager unit, why upgrades are described as replacing one file, and why the backup advice is about copying a directory.

The runtime floor is Java 17. The feature list covers public and private repositories over both http and ssh, GitLFS support, a repository viewer with an online file editor, issues, pull requests, and wikis, an activity timeline with email notifications, account and group management with LDAP integration, and a plug-in system. For an organization that wants internal Git hosting without running a container platform, that is a real and complete surface.

The one place the packaging shows its age is the servlet container story. The documentation says you can also deploy the war to a container supporting Servlet 3.0, naming Jetty, Tomcat, and JBoss, and then adds a caveat worth reading twice: GitBucket does not support Jakarta EE yet. That single sentence is the compatibility boundary. The major Servlet and Jakarta namespace rename broke many Java server applications in this exact way, and GitBucket is on the pre rename side of it. If your infrastructure standard has moved to Jakarta, you are outside the supported set and would need to run the bundled container instead.

Everything at the root of the repository reinforces the single artifact model. There is one `build.sbt`, a `project/` directory holding the sbt build definition, and a `contrib/` folder alongside a `doc/` directory that carries the Developer's Guide. The build is driven by sbt with committed launcher scripts, and dependency versions are managed by Scala Steward through a `.scala-steward.conf` file, with formatting pinned in `.scalafmt.conf`. A single Scala application, kept current by automation, rather than a multi module platform.

GitHub API compatibility as a first class feature

The project lists API compatibility with GitHub as one of four headline properties, alongside easy installation, an intuitive UI, and high extensibility by plugins. It is listed that way because it is the feature that makes the project substitutable. A team can move an internal tool from github.com to a self hosted GitBucket without rewriting the client, which turns a procurement decision into a configuration change.

Version 4.48.0, published on 2026-09-20, shows how that compatibility surface is still growing. The release adds a numeric user and account id to the GitHub compatibility API, plus a new API for managing users by that numeric id. Numeric ids are the kind of detail that only becomes visible when an integration needs stable identifiers across a migration, so the addition addresses a real gap rather than a hypothetical one.

The same release carries a warning that deserves attention from anyone running plugins. Authentication related API changes were included, and the release note states plainly that some plugins might not work with this version. The project's stated priority is the ease of installation and GitHub API compatibility, and it says outright that a feature request might be rejected if it goes against those principles. That is a useful thing to know before proposing a change: the roadmap is filtered through two constraints, and plugin compatibility can be sacrificed to preserve them.

Two other 4.48.0 items are more mundane but tell you about the project's maturity. A bug in the prevention of deleting the last admin user was fixed, which is the kind of defect that only surfaces in a long lived system, and a Danger zone tab was added to the user settings page, which is a UI affordance that lets destructive account operations be confirmed deliberately rather than by accident.

The open issue count sits at 332 on a repository with 9,405 stars and 1,269 forks. That ratio, roughly seven forks per hundred stars, is low compared to projects of comparable visibility, and it is consistent with a codebase that most people adopt as a binary rather than extend directly.

The plugin system and its officially supported set

Extensibility is handled by a plug-in system, and the officially provided plugins are deliberately few and each addresses a capability the core does not ship.

The `gitbucket-gist-plugin` adds gist support, which is the standard way to share snippets that do not warrant a repository. The `gitbucket-emoji-plugin` adds comment rendering for emoji shortcodes, a small feature that teams notice immediately when it is missing. The `gitbucket-pages-plugin` adds repository-backed static site publishing, and the `gitbucket-notifications-plugin` adds richer notification handling beyond the built in activity timeline and email notifications.

Read together, those four show a clear division of labor. Gists and pages are hosting features that require their own storage and routing decisions, emoji is a presentation concern, and notifications are an integration concern. None of them is something the core needs in order to function, and all of them are things a self hosted team is likely to want. That is the right shape for an official plugin set: a small number of composable additions rather than a feature checklist competing with the core.

Beyond the official set, the documentation points to a community plugin listing hosted on the project wiki. The presence of that list is itself a signal about the plugin system's reach. The caveat is the one stated in the release notes above: because plugin authors build against the same internal API surface as the core, a major version that changes authentication behavior can break third party plugins that the project does not control.

For an evaluation, the practical question is whether the capabilities you are missing are covered by one of these four, by a community plugin, or by a fork. The first is cheap, the second needs a health check on the specific plugin, and the third means you now maintain GitBucket.

Upgrades and the database migration you cannot skip

This is the part of operating GitBucket that deserves the most planning, because the upgrade is simple and the database is not.

The normal procedure is to stop GitBucket, replace `gitbucket.war` with the new version, and start again. All GitBucket data is stored under `HOME/.gitbucket` by default, so a backup is a directory copy. There is no database server to dump in the common case, which is the entire appeal of the packaging model and also the reason the backup advice can be so simple.

The complication is a specific version boundary. Versions 4.47.0 and 4.48.0 contain large database migrations affecting core tables such as `REPOSITORY` and `ACCOUNT`, and the release note says in strong terms that backing up the database before upgrading is recommended. Those two tables hold almost everything that makes an instance unique, so a failed migration is not a recoverable inconvenience.

A second boundary is older and nastier, because it cannot be automated. Upgrading from 4.42 or earlier to 4.43 or later on the default H2 database requires a manual dump and recreate, because H2 1.x and H2 2.x are not compatible. The project is explicit that GitBucket's automatic migration mechanism relies on the database itself and therefore cannot perform this step, so the operator has to run it by hand.

The documented procedure exports with the old H2 version and replays into the new one.

# Export database using the current version of H2
$ curl -O https://repo1.maven.org/maven2/com/h2database/h2/1.4.199/h2-1.4.199.jar
$ java -cp h2-1.4.199.jar org.h2.tools.Script -url "jdbc:h2:~/.gitbucket/data" -user sa -password sa -script dump.sql

The second half recreates the database using the newer H2 release.

# Recreate database using the new version of H2
$ curl -O https://repo1.maven.org/maven2/com/h2database/h2/2.3.232/h2-2.3.232.jar
$ java -cp h2-2.3.232.jar org.h2.tools.RunScript -url "jdbc:h2:~/.gitbucket/data" -user sa -password sa -script dump.sql

There is a follow-on configuration change, because the connection string carries a setting the new version rejects.

db {
  url = "jdbc:h2:${DatabaseHome};MVCC=true" // => "jdbc:h2:${DatabaseHome}"
  ...
}

The MVCC parameter has to be removed from the url in the database configuration file. An instance sitting on 4.42 or earlier therefore has a genuine maintenance task on the next upgrade, not just a file swap.

Sizing the project against its activity

The repository reports a last push on the default branch of 2026-09-20, which is well within a 183 day window from this writing and supports calling the project actively maintained. The release cadence supports the same conclusion: 4.47.0 on 2026-08-09, 4.47.1 on 2026-09-16, and 4.48.0 on 2026-09-20 put three releases inside six weeks, with a patch release landing six days after the minor one.

That pattern, a frequent minor release followed quickly by a patch, is worth noting alongside the database warnings. A project releasing this often is a project accumulating migrations, which is exactly what the notes describe. The two facts are not in conflict, but they do mean that an operator's real task is not installing GitBucket, which is trivial, but deciding which version to run and when to absorb a migration.

The distribution numbers give a rough sense of adoption. At 9,405 stars and 1,269 forks, GitBucket is well known in the self hosted Git space, though it operates at a fraction of the visibility of the largest forges. That is consistent with its stated audience. It is a tool for organizations that want Git hosting they control with an API surface they already know, not a competitor for the public hosting market.

The support guidance in the documentation reflects that audience too. Questions are directed to the wiki first, then to the Gitter chat room before raising an issue, which reduces duplicate reports in a project with a substantial backlog. Contributors are pointed at the Developer's Guide, which the documentation describes as covering both building from source and the core concepts used within the project, and that second part matters more than it sounds. A Scala codebase with an unusual plugin architecture is a difficult contribution target without an explanation of its internal model, and providing one is a real investment by the maintainers.

Editorial conclusion

GitBucket trades modern packaging for operability you can reason about: one war file on Java 17, data under a single directory, and an API that keeps existing clients working. Plan the 4.42 to 4.43 database step before you need it, since the project cannot automate it.

Frequently asked questions

Official sources

1. gitbucket/gitbucket on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases