James Moger
2014-05-12 edeab95cac16e5f17cfcd75a9969d8708bf360ab
commit | author | age
c5dfd6 1
JM 2 ## Gitblit Plugins
3
4 *SINCE 1.5.0*
5
6 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.
7
8 ### What is a plugin?
9
10 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*.
11
12 *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*.
13
14 ### Architecture
15
16 The existing plugin mechanism is based on [pf4j](https://github.com/decebals/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.
17
5b3669 18 The plugin zip files are stored in `${baseFolder}/plugins` and are unpacked on startup into folders of the same name.
c5dfd6 19
JM 20 A plugin defines it's metadata in the META-INF/MANIFEST.MF file:
21
22     Plugin-Id: powertools
a3ac80 23     Plugin-Description: Command and control Gitblit over SSH
5b3669 24     Plugin-Class: com.gitblit.plugin.powertools.Plugin
c5dfd6 25     Plugin-Version: 1.2.0
2d73a0 26     Plugin-Requires: 1.5.0
c5dfd6 27     Plugin-Provider: gitblit.com
JM 28
29 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.
30
31     Plugin-Dependencies: foo, bar
32
33 **NOTE:**
34 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.
35
5b3669 36 #### Limitations of Plugin Dependencies
c5dfd6 37
5b3669 38 Plugins may specify plugin dependencies by their ID, but they may not specify dependency versions.
c5dfd6 39
JM 40 ### Managing Plugins
41
42 Administrators may manage plugins through the `plugin` SSH dispatch command:
43
5b3669 44     ssh host -l username -p 29418 plugin
c5dfd6 45
5b3669 46 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.
c5dfd6 47
edeab9 48 You may watch an Asciinema screencast of how to use the SSH transport and the plugin manager [here](https://asciinema.org/a/9342).
JM 49
c5dfd6 50 ### Default Plugin Registry
JM 51
52 Gitblit provides a simple default registry of plugins. The registry is a JSON file and it lists plugin metadata and download locations.
53
54     plugins.registry = http://plugins.gitblit.com/plugins.json
55
56 The [registry](http://plugins.gitblit.com/plugins.json) is currently hosted in a [Git repository on Github](https://github.com/gitblit/gitblit-registry).  This git repository is also a [Maven-compatible repository](http://plugins.gitblit.com), which hosts some plugin binaries.
57
58 ### Contributing Plugins to the Default Registry
59
5b3669 60 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.
c5dfd6 61
JM 62 ### Hosting your Own Registry / Allowing Multiple Registries
63
5b3669 64 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.
c5dfd6 65
JM 66 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.