Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

gitbucket-h2-backup-plugin Gitter Travis

This plugin enhances GitBucket by offering a way to backup/dump the entire H2 database of GitBucket.

It originates from pull request #845 and can be used to address database backup described in GitBucket Backup Documentation


H2 Backup

This plugin allows you to backup the underlying H2 database used by default by GitBucket.


The plugin provides two ways to backup the H2 database:

  • via an administration page and a backup button
  • via an HTTP call to http://YOUR_GITBUCKET/api/v3/plugins/database/backup

The default backup file points to GITBUCKET_DATA/backup/ where:

  • GITBUCKET_DATA is the standard GitBucket data directory. If not specified, default it's ~/.gitbucket
  • YYYY-MM-DD-hhmm represents a date with hour and minutes

UI usage

  • goto the System Administration menu, section H2 Backup
  • modify the file path if the default one doesn't fit your needs
  • hit the Export database button

backup ui

HTTP call usage

Using your preferred tool (curl, wget, ...) it is possible start a backup of the H2 database.

The URL to call looks like http://YOUR_GITBUCKET/api/v3/plugins/database/backup

You can pass an optional argument dest that references the destination file path where the backup will be done on the server. For example calling http://YOUR_GITBUCKET/api/v3/plugins/database/backup?dest=/var/backups/ will do an H2 backup of the gitbucket database into the file /var/backups/ Since 1.3.0, the dest parameter can denote a relative file path, in this case the file will be created relatively to GITBUCKET_DATA.

On success, you will receive a HTTP 200 answer with a text/plain body containing the name of the backup file, without a path component. The file is in the GITBUCKET_DATA/backup folder.

HTTP API Authorization

The api uses token authentication. To generate a token:

  1. Login to Gitbucket with an administrative account

  2. In the top-right corner, click the user menu

  3. Click Account Settings

  4. On the left, click Applications

  5. In Generate new token enter a description and click Generate token

  6. Add the token to your http call, such as with curl:

    curl --silent --show-error --fail -X POST -H 'Authorization: token your_token_value' http://YOUR_GITBUCKET/api/v3/plugins/database/backup


Plugin version GitBucket version
1.9.x >= 4.35.y
1.8.x >= 4.32.y
1.7.x >= 4.26.y
1.6.x >= 4.21.y
1.5.x >= 4.16.y
1.4.x >= 4.10.y
1.3.x >= 4.3.y
1.2.x 4.x.y
1.1.x 3.11.x
1.0.x 3.6.x, 3.7.x, 3.8.x,, 3.9.x, 3.10.x


sbt clean assembly


  • copy gitbucket-h2-backup.jar into GITBUCKET_HOME/plugins
  • restart GitBucket

Release Notes


  • remove backup api at GET /database/backup
  • change method from GET to POST on /api/v3/plugins/database/backup
  • backup endpoint is secure by default, and requires an api token for a user with admin rights


  • compatibility with GitBucket 4.35.x


  • compatibility with GitBucket 4.32.x and Scala 2.13



  • compatibility with GitBucket 4.21.x


  • compatibility with GitBucket 4.16.0 and Scala 2.12


  • compatibility with GitBucket 4.10, scala 2.12 #20
  • allow to secure database/backup endpoint #1,#19


  • compatibility with GitBucket 4.3.0
  • fix version order in GitBucket Plugins panel
  • default backup file contains date with timestamp #12


  • binary compatibility with GitBucket 4.x


  • recompilation to ensure binary compatibility with GitBucket 3.11


  • introduce gitbucket-h2-backup-plugin
  • allows to backup h2 database via a live dump