Gitblit Plugins

SINCE 1.5.0

Gitblit supports extending and enhancing the core functionality through plugins. This mechanism is very young and incomplete with few extension points, but you can expect it to evolve rapidly in upcoming releases.

What is a plugin?

A plugin is a collection of Java classes and required jar dependencies bundled together in a zip file. A plugin may optionally include Extensions which enhance Gitblit at specific Gitblit-specified ExtensionPoints.

Plugins are singleton instances that are STARTED when Gitblit launches and STOPPED when Gitblit terminates. Extensions are dynamic instances that are created when Gitblit processes requests that trigger ExtensionPoints.


The existing plugin mechanism is based on pf4j. Plugins are distributed as zip files and may include their runtime dependencies or may rely on the bundled dependencies of other plugins and/or Gitblit core.

The plugin zip files are stored in ${baseFolder}/plugins and are unpacked on startup into folders of the same name.

A plugin defines it's metadata in the META-INF/MANIFEST.MF file:

Plugin-Id: powertools
Plugin-Description: Command and control Gitblit over SSH
Plugin-Class: com.gitblit.plugin.powertools.Plugin
Plugin-Version: 1.2.0
Plugin-Requires: 1.5.0

In addition to extending Gitblit core, plugins can also define extension points that may be implemented by other plugins. Therefore a plugin may depend on other plugins.

Plugin-Dependencies: foo, bar

The pf4j plugin framework relies on a javac apt processor to generate compile-time extension information, so be sure to enable apt processing in your build process.

Limitations of Plugin Dependencies

Plugins may specify plugin dependencies by their ID, but they may not specify dependency versions.

Managing Plugins

Administrators may manage plugins through the plugin SSH dispatch command:

ssh host -l username -p 29418 plugin

Through this command interface plugins can be started, stopped, disabled, enabled, installed, uninstalled, listed, etc. Each command is supports the --help argument which will guide you in understanding the options and usage of the command.

You may watch an Asciinema screencast of how to use the SSH transport and the plugin manager here.

Default Plugin Registry

Gitblit provides a simple default registry of plugins. The registry is a JSON file and it lists plugin metadata and download locations.

plugins.registry =

The default plugins registry is currently hosted in a Git repository on Github. You can view the default registry file here. The default plugin registry is also a Maven-2 compatible repository.

Contributing Plugins to the Default Registry

If you develop your own plugins that you want hosted by or linked in the default registry, open a pull request for the registry repository. Any contributed binaries hosted in this repository must have Maven metadata and the SHA-1 & MD5 checksums. By default, Gitblit enforces checksum validation on all downloads.

Hosting your Own Registry / Allowing Multiple Registries

The plugins.json file is parameterized with the ${self} placeholder. This parameter is substituted on download with with the source URL of the registry file. This allows you to clone and serve your own copy of this git repository or just serve your own plugins.json on your own network.

Gitblit also supports loading multiple plugin registries. Just place another properly formatted .json file in ${baseFolder}/plugins and Gitblit will load that as an additional registry.