The Gerrit server functionality can be extended by installing plugins. This page describes how plugins for Gerrit can be developed.
Depending on how tightly the extension code is coupled with the Gerrit
server code, there is a distinction between plugins
and extensions
.
A plugin
in Gerrit is tightly coupled code that runs in the same
JVM as Gerrit. It has full access to all server internals. Plugins
are tightly coupled to a specific major.minor server version and
may require source code changes to compile against a different
server version.
An extension
in Gerrit runs inside of the same JVM as Gerrit
in the same way as a plugin, but has limited visibility to the
server’s internals. The limited visibility reduces the extension’s
dependencies, enabling it to be compatible across a wider range
of server versions.
Most of this documentation refers to either type as a plugin.
Getting started
To get started with the development of a plugin there are two recommended ways:
-
use the Gerrit Plugin Maven archetype to create a new plugin project:
With the Gerrit Plugin Maven archetype you can create a skeleton for a plugin project.
mvn archetype:generate -DarchetypeGroupId=com.google.gerrit \ -DarchetypeArtifactId=gerrit-plugin-archetype \ -DarchetypeVersion=2.8-SNAPSHOT \ -DgroupId=com.google.gerrit \ -DartifactId=testPlugin
Maven will ask for additional properties and then create the plugin in the current directory. To change the default property values answer n when Maven asks to confirm the properties configuration. It will then ask again for all properties including those with predefined default values.
-
clone the sample plugin:
This is a project that demonstrates the various features of the plugin API. It can be taken as an example to develop an own plugin.
$ git clone https://gerrit.googlesource.com/plugins/cookbook-plugin
When starting from this example one should take care to adapt the
Gerrit-ApiVersion
in thepom.xml
to the version of Gerrit for which the plugin is developed. If the plugin is developed for a released Gerrit version (noSNAPSHOT
version) then the URL for thegerrit-api-repository
in thepom.xml
needs to be changed tohttps://gerrit-api.storage.googleapis.com/release/
.
API
There are two different API formats offered against which plugins can be developed:
- gerrit-extension-api.jar
-
A stable but thin interface. Suitable for extensions that need to be notified of events, but do not require tight coupling to the internals of Gerrit. Extensions built against this API can expect to be binary compatible across a wide range of server versions.
- gerrit-plugin-api.jar
-
The complete internals of the Gerrit server, permitting a plugin to tightly couple itself and provide additional functionality that is not possible as an extension. Plugins built against this API are expected to break at the source code level between every major.minor Gerrit release. A plugin that compiles against 2.5 will probably need source code level changes to work with 2.6, 2.7, and so on.
Manifest
Plugins may provide optional description information with standard manifest fields:
Implementation-Title: Example plugin showing examples Implementation-Version: 1.0 Implementation-Vendor: Example, Inc. Implementation-URL: http://example.com/opensource/plugin-foo/
ApiType
Plugins using the tightly coupled gerrit-plugin-api.jar
must
declare this API dependency in the manifest to gain access to server
internals. If no Gerrit-ApiType
is specified the stable extension
API will be assumed. This may cause ClassNotFoundExceptions when
loading a plugin that needs the plugin API.
Gerrit-ApiType: plugin
Explicit Registration
Plugins that use explicit Guice registration must name the Guice
modules in the manifest. Up to three modules can be named in the
manifest. Gerrit-Module
supplies bindings to the core server;
Gerrit-SshModule
supplies SSH commands to the SSH server (if
enabled); Gerrit-HttpModule
supplies servlets and filters to the HTTP
server (if enabled). If no modules are named automatic registration
will be performed by scanning all classes in the plugin JAR for
@Listen
and @Export("")
annotations.
Gerrit-Module: tld.example.project.CoreModuleClassName Gerrit-SshModule: tld.example.project.SshModuleClassName Gerrit-HttpModule: tld.example.project.HttpModuleClassName
Plugin Name
A plugin can optionally provide its own plugin name.
Gerrit-PluginName: replication
This is useful for plugins that contribute plugin-owned capabilities that
are stored in the project.config
file. Another use case is to be able to put
project specific plugin configuration section in project.config
. In this
case it is advantageous to reserve the plugin name to access the configuration
section in the project.config
file.
If Gerrit-PluginName
is omitted, then the plugin’s name is determined from
the plugin file name.
If a plugin provides its own name, then that plugin cannot be deployed multiple times under different file names on one Gerrit site.
For Maven driven plugins, the following line must be included in the pom.xml file:
<manifestEntries>
<Gerrit-PluginName>name</Gerrit-PluginName>
</manifestEntries>
For Buck driven plugins, the following line must be included in the BUCK configuration file:
manifest_entries = [
'Gerrit-PluginName: name',
]
A plugin can get its own name injected at runtime:
public class MyClass {
private final String pluginName;
@Inject
public MyClass(@PluginName String pluginName) {
this.pluginName = pluginName;
}
[...]
}
Reload Method
If a plugin holds an exclusive resource that must be released before
loading the plugin again (for example listening on a network port or
acquiring a file lock) the manifest must declare Gerrit-ReloadMode
to be restart
. Otherwise the preferred method of reload
will
be used, as it enables the server to hot-patch an updated plugin
with no down time.
Gerrit-ReloadMode: restart
In either mode (restart or reload) any plugin or extension can be updated without restarting the Gerrit server. The difference is how Gerrit handles the upgrade:
- restart
-
The old plugin is completely stopped. All registrations of SSH commands and HTTP servlets are removed. All registrations of any extension points are removed. All registered LifecycleListeners have their
stop()
method invoked in reverse order. The new plugin is started, and registrations are made from the new plugin. There is a brief window where neither the old nor the new plugin is connected to the server. This means SSH commands and HTTP servlets will return not found errors, and the plugin will not be notified of events that occurred during the restart. - reload
-
The new plugin is started. Its LifecycleListeners are permitted to perform their
start()
methods. All SSH and HTTP registrations are atomically swapped out from the old plugin to the new plugin, ensuring the server never returns a not found error. All extension point listeners are atomically swapped out from the old plugin to the new plugin, ensuring no events are missed (however some events may still route to the old plugin if the swap wasn’t complete yet). The old plugin is stopped.
To reload/restart a plugin the plugin reload command can be used.
Init step
Plugins can contribute their own "init step" during the Gerrit init wizard. This is useful for guiding the Gerrit administrator through the settings needed by the plugin to work propertly.
For instance plugins to integrate Jira issues to Gerrit changes may contribute their own "init step" to allow configuring the Jira URL, credentials and possibly verify connectivity to validate them.
Gerrit-InitStep: tld.example.project.MyInitStep
MyInitStep needs to follow the standard Gerrit InitStep syntax and behavior: writing to the console using the injected ConsoleUI and accessing / changing configuration settings using Section.Factory.
In addition to the standard Gerrit init injections, plugins receive the @PluginName String injection containing their own plugin name.
Bear in mind that the Plugin’s InitStep class will be loaded but the standard Gerrit runtime environment is not available and the plugin’s own Guice modules were not initialized. This means the InitStep for a plugin is not executed in the same way that the plugin executes within the server, and may mean a plugin author cannot trivially reuse runtime code during init.
For instance a plugin that wants to verify connectivity may need to statically call the constructor of their connection class, passing in values obtained from the Section.Factory rather than from an injected Config object.
Plugins' InitSteps are executed during the "Gerrit Plugin init" phase, after
the extraction of the plugins embedded in the distribution .war file into
$GERRIT_SITE/plugins
and before the DB Schema initialization or upgrade.
A plugin’s InitStep cannot refer to Gerrit’s DB Schema or any other Gerrit runtime objects injected at startup.
public class MyInitStep implements InitStep {
private final ConsoleUI ui;
private final Section.Factory sections;
private final String pluginName;
@Inject
public GitBlitInitStep(final ConsoleUI ui, Section.Factory sections, @PluginName String pluginName) {
this.ui = ui;
this.sections = sections;
this.pluginName = pluginName;
}
@Override
public void run() throws Exception {
ui.header("\nMy plugin");
Section mySection = getSection("myplugin", null);
mySection.string("Link name", "linkname", "MyLink");
}
}
Classpath
Each plugin is loaded into its own ClassLoader, isolating plugins
from each other. A plugin or extension inherits the Java runtime
and the Gerrit API chosen by Gerrit-ApiType
(extension or plugin)
from the hosting server.
Plugins are loaded from a single JAR file. If a plugin needs additional libraries, it must include those dependencies within its own JAR. Plugins built using Maven may be able to use the shade plugin to package additional dependencies. Relocating (or renaming) classes should not be necessary due to the ClassLoader isolation.
Listening to Events
Certain operations in Gerrit trigger events. Plugins may receive notifications of these events by implementing the corresponding listeners.
-
com.google.gerrit.common.ChangeListener
:Allows to listen to change events. These are the same events that are also streamed by the gerrit stream-events command.
-
com.google.gerrit.extensions.events.LifecycleListener
:Gerrit server startup and shutdown
-
com.google.gerrit.extensions.events.NewProjectCreatedListener
:Project creation
-
com.google.gerrit.extensions.events.ProjectDeletedListener
:Project deletion
Sending Events to the Events Stream
Plugins may send events to the events stream where consumers of
Gerrit’s stream-events
ssh command will receive them.
To send an event, the plugin must invoke one of the postEvent
methods in the ChangeHookRunner
class, passing an instance of
its own custom event class derived from ChangeEvent
.
Validation Listeners
Certain operations in Gerrit can be validated by plugins by implementing the corresponding listeners.
SSH Commands
Plugins may provide commands that can be accessed through the SSH interface (extensions do not have this option).
Command implementations must extend the base class SshCommand:
import com.google.gerrit.sshd.SshCommand;
class PrintHello extends SshCommand {
protected abstract void run() {
stdout.print("Hello\n");
}
}
If no Guice modules are declared in the manifest, SSH commands may
use auto-registration by providing an @Export
annotation:
import com.google.gerrit.extensions.annotations.Export;
import com.google.gerrit.sshd.SshCommand;
@Export("print")
class PrintHello extends SshCommand {
protected abstract void run() {
stdout.print("Hello\n");
}
}
If explicit registration is being used, a Guice module must be
supplied to register the SSH command and declared in the manifest
with the Gerrit-SshModule
attribute:
import com.google.gerrit.sshd.PluginCommandModule;
class MyCommands extends PluginCommandModule {
protected void configureCommands() {
command("print").to(PrintHello.class);
}
}
For a plugin installed as name helloworld
, the command implemented
by PrintHello class will be available to users as:
$ ssh -p 29418 review.example.com helloworld print
Multiple SSH commands can be bound to the same implementation class. For example a Gerrit Shell plugin can bind different shell commands to the same implementation class:
public class SshShellModule extends PluginCommandModule {
@Override
protected void configureCommands() {
command("ls").to(ShellCommand.class);
command("ps").to(ShellCommand.class);
[...]
}
}
With the possible implementation:
public class ShellCommand extends SshCommand {
@Override
protected void run() throws UnloggedFailure {
String cmd = getName().substring(getPluginName().length() + 1);
ProcessBuilder proc = new ProcessBuilder(cmd);
Process cmd = proc.start();
[...]
}
}
And the call:
$ ssh -p 29418 review.example.com shell ls $ ssh -p 29418 review.example.com shell ps
Configuration
In Gerrit, global configuration is stored in the gerrit.config
file.
If a plugin needs global configuration, this configuration should be
stored in a plugin
subsection in the gerrit.config
file.
This approach of storing the plugin configuration is only suitable for
plugins that have a simple configuration that only consists of
key-value pairs. With this approach it is not possible to have
subsections in the plugin configuration. Plugins that require a complex
configuration need to store their configuration in their own
configuration file where they can make use of subsections. On the other
hand storing the plugin configuration in a plugin subsection in the
gerrit.config
file has the advantage that administrators have all
configuration parameters in one file, instead of having one
configuration file per plugin.
To avoid conflicts with other plugins, it is recommended that plugins
only use the plugin
subsection with their own name. For example the
helloworld
plugin should store its configuration in the
plugin.helloworld
subsection:
[plugin "helloworld"] language = Latin
Via the com.google.gerrit.server.config.PluginConfigFactory
class a
plugin can easily access its configuration and there is no need for a
plugin to parse the gerrit.config
file on its own:
@Inject
private com.google.gerrit.server.config.PluginConfigFactory cfg;
[...]
String language = cfg.getFromGerritConfig("helloworld")
.getString("language", "English");
Project Specific Configuration
In Gerrit, project specific configuration is stored in the project’s
project.config
file on the refs/meta/config
branch. If a plugin
needs configuration on project level (e.g. to enable its functionality
only for certain projects), this configuration should be stored in a
plugin
subsection in the project’s project.config
file.
This approach of storing the plugin configuration is only suitable for
plugins that have a simple configuration that only consists of
key-value pairs. With this approach it is not possible to have
subsections in the plugin configuration. Plugins that require a complex
configuration need to store their configuration in their own
configuration file where they can make use of subsections. On the other
hand storing the plugin configuration in a plugin subsection in the
project.config
file has the advantage that project owners have all
configuration parameters in one file, instead of having one
configuration file per plugin.
To avoid conflicts with other plugins, it is recommended that plugins
only use the plugin
subsection with their own name. For example the
helloworld
plugin should store its configuration in the
plugin.helloworld
subsection:
[plugin "helloworld"] enabled = true
Via the com.google.gerrit.server.config.PluginConfigFactory
class a
plugin can easily access its project specific configuration and there
is no need for a plugin to parse the project.config
file on its own:
@Inject
private com.google.gerrit.server.config.PluginConfigFactory cfg;
[...]
boolean enabled = cfg.getFromProjectConfig(project, "helloworld")
.getBoolean("enabled", false);
It is also possible to get missing configuration parameters inherited from the parent projects:
@Inject
private com.google.gerrit.server.config.PluginConfigFactory cfg;
[...]
boolean enabled = cfg.getFromProjectConfigWithInheritance(project, "helloworld")
.getBoolean("enabled", false);
Project owners can edit the project configuration by fetching the
refs/meta/config
branch, editing the project.config
file and
pushing the commit back.
Plugin Owned Capabilities
Plugins may provide their own capabilities and restrict usage of SSH commands to the users who are granted those capabilities.
Plugins define the capabilities by overriding the CapabilityDefinition
abstract class:
public class PrintHelloCapability extends CapabilityDefinition {
@Override
public String getDescription() {
return "Print Hello";
}
}
If no Guice modules are declared in the manifest, UI actions may
use auto-registration by providing an @Export
annotation:
@Export("printHello")
public class PrintHelloCapability extends CapabilityDefinition {
[...]
}
Otherwise the capability must be bound in a plugin module:
public class HelloWorldModule extends AbstractModule {
@Override
protected void configure() {
bind(CapabilityDefinition.class)
.annotatedWith(Exports.named("printHello"))
.to(PrintHelloCapability.class);
}
}
With a plugin-owned capability defined in this way, it is possible to restrict
usage of an SSH command or UiAction
to members of the group that were granted
this capability in the usual way, using the RequiresCapability
annotation:
@RequiresCapability("printHello")
@CommandMetaData(name="print", description="Print greeting in different languages")
public final class PrintHelloWorldCommand extends SshCommand {
[...]
}
Or with UiAction
:
@RequiresCapability("printHello")
public class SayHelloAction extends UiAction<RevisionResource>
implements RestModifyView<RevisionResource, SayHelloAction.Input> {
[...]
}
Capability scope was introduced to differentiate between plugin-owned
capabilities and core capabilities. Per default the scope of the
@RequiresCapability
annotation is CapabilityScope.CONTEXT
, that means:
-
when
@RequiresCapability
is used within a plugin the scope of the capability is assumed to be that plugin. -
If
@RequiresCapability
is used within the core Gerrit Code Review server (and thus is outside of a plugin) the scope is the core server and will use theGlobalCapability
known to Gerrit Code Review server.
If a plugin needs to use a core capability name (e.g. "administrateServer")
this can be specified by setting scope = CapabilityScope.CORE
:
@RequiresCapability(value = "administrateServer", scope =
CapabilityScope.CORE)
[...]
UI Extension
Plugins can contribute UI actions on core Gerrit pages. This is useful for workflow customization or exposing plugin functionality through the UI in addition to SSH commands and the REST API.
For instance a plugin to integrate Jira with Gerrit changes may contribute a "File bug" button to allow filing a bug from the change page or plugins to integrate continuous integration systems may contribute a "Schedule" button to allow a CI build to be scheduled manually from the patch set panel.
Two different places on core Gerrit pages are supported:
-
Change screen
-
Project info screen
Plugins contribute UI actions by implementing the UiAction
interface:
@RequiresCapability("printHello")
class HelloWorldAction implements UiAction<RevisionResource>,
RestModifyView<RevisionResource, HelloWorldAction.Input> {
static class Input {
boolean french;
String message;
}
private Provider<CurrentUser> user;
@Inject
HelloWorldAction(Provider<CurrentUser> user) {
this.user = user;
}
@Override
public String apply(RevisionResource rev, Input input) {
final String greeting = input.french
? "Bonjour"
: "Hello";
return String.format("%s %s from change %s, patch set %d!",
greeting,
Strings.isNullOrEmpty(input.message)
? Objects.firstNonNull(user.get().getUserName(), "world")
: input.message,
rev.getChange().getId().toString(),
rev.getPatchSet().getPatchSetId());
}
@Override
public Description getDescription(
RevisionResource resource) {
return new Description()
.setLabel("Say hello")
.setTitle("Say hello in different languages");
}
}
Sometimes plugins may want to be able to change the state of a patch set or
change in the UiAction.apply()
method and reflect these changes on the core
UI. For example a buildbot plugin which exposes a Schedule button on the
patch set panel may want to disable that button after the build was scheduled
and update the tooltip of that button. But because of Gerrit’s caching
strategy the following must be taken into consideration.
The browser is allowed to cache the UiAction
information until something on
the change is modified. More accurately the change row needs to be modified in
the database to have a more recent lastUpdatedOn
or a new rowVersion
, or
the refs/meta/config
of the project or any parents needs to change to a new
SHA-1. The ETag SHA-1 computation code can be found in the
ChangeResource.getETag()
method.
The easiest way to accomplish this is to update lastUpdatedOn
of the change:
@Override
public Object apply(RevisionResource rcrs, Input in) {
// schedule a build
[...]
// update change
ReviewDb db = dbProvider.get();
db.changes().beginTransaction(change.getId());
try {
change = db.changes().atomicUpdate(
change.getId(),
new AtomicUpdate<Change>() {
@Override
public Change update(Change change) {
ChangeUtil.updated(change);
return change;
}
});
db.commit();
} finally {
db.rollback();
}
[...]
}
UiAction
must be bound in a plugin module:
public class Module extends AbstractModule {
@Override
protected void configure() {
install(new RestApiModule() {
@Override
protected void configure() {
post(REVISION_KIND, "say-hello")
.to(HelloWorldAction.class);
}
});
}
}
The module above must be declared in the pom.xml
for Maven driven
plugins:
<manifestEntries>
<Gerrit-Module>com.googlesource.gerrit.plugins.cookbook.Module</Gerrit-Module>
</manifestEntries>
or in the BUCK
configuration file for Buck driven plugins:
manifest_entries = [
'Gerrit-Module: com.googlesource.gerrit.plugins.cookbook.Module',
]
In some use cases more user input must be gathered, for that UiAction
can be
combined with the JavaScript API. This would display a small popup near the
activation button to gather additional input from the user. The JS file is
typically put in the static
folder within the plugin’s directory:
Gerrit.install(function(self) {
function onSayHello(c) {
var f = c.textfield();
var t = c.checkbox();
var b = c.button('Say hello', {onclick: function(){
c.call(
{message: f.value, french: t.checked},
function(r) {
c.hide();
window.alert(r);
c.refresh();
});
}});
c.popup(c.div(
c.prependLabel('Greeting message', f),
c.br(),
c.label(t, 'french'),
c.br(),
b));
f.focus();
}
self.onAction('revision', 'say-hello', onSayHello);
});
The JS module must be exposed as a WebUiPlugin
and bound as
an HTTP Module:
public class HttpModule extends HttpPluginModule {
@Override
protected void configureServlets() {
DynamicSet.bind(binder(), WebUiPlugin.class)
.toInstance(new JavaScriptPlugin("hello.js"));
}
}
The HTTP module above must be declared in the pom.xml
for Maven
driven plugins:
<manifestEntries>
<Gerrit-HttpModule>com.googlesource.gerrit.plugins.cookbook.HttpModule</Gerrit-HttpModule>
</manifestEntries>
or in the BUCK
configuration file for Buck driven plugins
manifest_entries = [
'Gerrit-HttpModule: com.googlesource.gerrit.plugins.cookbook.HttpModule',
]
If UiAction
is annotated with the @RequiresCapability
annotation, then the
capability check is done during the UiAction
gathering, so the plugin author
doesn’t have to set UiAction.Description.setVisible()
explicitly in this
case.
The following prerequisities must be met, to satisfy the capability check:
-
user is authenticated
-
user is a member of a group which has the
Administrate Server
capability, or -
user is a member of a group which has the required capability
The apply
method is called when the button is clicked. If UiAction
is
combined with JavaScript API (its own JavaScript function is provided),
then a popup dialog is normally opened to gather additional user input.
A new button is placed on the popup dialog to actually send the request.
Every UiAction
exposes a REST API endpoint. The endpoint from the example above
can be accessed from any REST client, i. e.:
curl -X POST -H "Content-Type: application/json" \ -d '{message: "François", french: true}' \ --digest --user joe:secret \ http://host:port/a/changes/1/revisions/1/cookbook~say-hello "Bonjour François from change 1, patch set 1!"
A special case is to bind an endpoint without a view name. This is
particularly useful for DELETE
requests:
public class Module extends AbstractModule {
@Override
protected void configure() {
install(new RestApiModule() {
@Override
protected void configure() {
delete(PROJECT_KIND)
.to(DeleteProject.class);
}
});
}
}
For a UiAction
bound this way, a JS API function can be provided.
Currently only one restriction exists: per plugin only one UiAction
can be bound per resource without view name. To define a JS function
for the UiAction
, "/" must be used as the name:
Gerrit.install(function(self) {
function onDeleteProject(c) {
[...]
}
self.onAction('project', '/', onDeleteProject);
});
Top Menu Extensions
Plugins can contribute items to Gerrit’s top menu.
A single top menu extension can have multiple elements and will be put as the last element in Gerrit’s top menu.
Plugins define the top menu entries by implementing TopMenu
interface:
public class MyTopMenuExtension implements TopMenu {
@Override
public List<MenuEntry> getEntries() {
return Lists.newArrayList(
new MenuEntry("Top Menu Entry", Lists.newArrayList(
new MenuItem("Gerrit", "http://gerrit.googlecode.com/"))));
}
}
Plugins can also add additional menu items to Gerrit’s top menu entries
by defining a MenuEntry
that has the same name as a Gerrit top menu
entry:
public class MyTopMenuExtension implements TopMenu {
@Override
public List<MenuEntry> getEntries() {
return Lists.newArrayList(
new MenuEntry(GerritTopMenu.PROJECTS, Lists.newArrayList(
new MenuItem("Browse Repositories", "https://gerrit.googlesource.com/"))));
}
}
If no Guice modules are declared in the manifest, the top menu extension may use
auto-registration by providing an @Listen
annotation:
@Listen
public class MyTopMenuExtension implements TopMenu {
[...]
}
Otherwise the top menu extension must be bound in the plugin module used for the Gerrit system injector (Gerrit-Module entry in MANIFEST.MF):
package com.googlesource.gerrit.plugins.helloworld;
public class HelloWorldModule extends AbstractModule {
@Override
protected void configure() {
DynamicSet.bind(binder(), TopMenu.class).to(MyTopMenuExtension.class);
}
}
Gerrit-ApiType: plugin
Gerrit-Module: com.googlesource.gerrit.plugins.helloworld.HelloWorldModule
HTTP Servlets
Plugins or extensions may register additional HTTP servlets, and wrap them with HTTP filters.
Servlets may use auto-registration to declare the URL they handle:
import com.google.gerrit.extensions.annotations.Export;
import com.google.inject.Singleton;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
@Export("/print")
@Singleton
class HelloServlet extends HttpServlet {
protected void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException {
res.setContentType("text/plain");
res.setCharacterEncoding("UTF-8");
res.getWriter().write("Hello");
}
}
The auto registration only works for standard servlet mappings like
/foo
or /foo/*
. Regex style bindings must use a Guice ServletModule
to register the HTTP servlets and declare it explicitly in the manifest
with the Gerrit-HttpModule
attribute:
import com.google.inject.servlet.ServletModule;
class MyWebUrls extends ServletModule {
protected void configureServlets() {
serve("/print").with(HelloServlet.class);
}
}
For a plugin installed as name helloworld
, the servlet implemented
by HelloServlet class will be available to users as:
$ curl http://review.example.com/plugins/helloworld/print
Data Directory
Plugins can request a data directory with a @PluginData
File
dependency. A data directory will be created automatically by the
server in $site_path/data/$plugin_name
and passed to the plugin.
Plugins can use this to store any data they want.
@Inject
MyType(@PluginData java.io.File myDir) {
new FileInputStream(new File(myDir, "my.config"));
}
Download Commands
Gerrit offers commands for downloading changes using different
download schemes (e.g. for downloading via different network
protocols). Plugins can contribute download schemes and download
commands by implementing
com.google.gerrit.extensions.config.DownloadScheme
and
com.google.gerrit.extensions.config.DownloadCommand
.
The download schemes and download commands which are used most often
are provided by the Gerrit core plugin download-commands
.
Documentation
If a plugin does not register a filter or servlet to handle URLs
/Documentation/*
or /static/*
, the core Gerrit server will
automatically export these resources over HTTP from the plugin JAR.
Static resources under the static/
directory in the JAR will be
available as /plugins/helloworld/static/resource
. This prefix is
configurable by setting the Gerrit-HttpStaticPrefix
attribute.
Documentation files under the Documentation/
directory in the JAR
will be available as /plugins/helloworld/Documentation/resource
. This
prefix is configurable by setting the Gerrit-HttpDocumentationPrefix
attribute.
Documentation may be written in
Markdown style
if the file name ends with .md
. Gerrit will automatically convert
Markdown to HTML if accessed with extension .html
.
Within the Markdown documentation files macros can be used that allow to write documentation with reasonably accurate examples that adjust automatically based on the installation.
The following macros are supported:
Macro | Replacement |
---|---|
@PLUGIN@ |
name of the plugin |
@URL@ |
Gerrit Web URL |
@SSH_HOST@ |
SSH Host |
@SSH_PORT@ |
SSH Port |
The macros will be replaced when the documentation files are rendered from Markdown to HTML.
Macros that start with \
such as \@KEEP@
will render as @KEEP@
even if there is an expansion for KEEP
in the future.
Automatic Index
If a plugin does not handle its /
URL itself, Gerrit will
redirect clients to the plugin’s /Documentation/index.html
.
Requests for /Documentation/
(bare directory) will also redirect
to /Documentation/index.html
.
If neither resource Documentation/index.html
or
Documentation/index.md
exists in the plugin JAR, Gerrit will
automatically generate an index page for the plugin’s documentation
tree by scanning every *.md
and *.html
file in the Documentation/
directory.
For any discovered Markdown (*.md
) file, Gerrit will parse the
header of the file and extract the first level one title. This
title text will be used as display text for a link to the HTML
version of the page.
For any discovered HTML (*.html
) file, Gerrit will use the name
of the file, minus the *.html
extension, as the link text. Any
hyphens in the file name will be replaced with spaces.
If a discovered file is named about.md
or about.html
, its
content will be inserted in an About section at the top of the
auto-generated index page. If both about.md
and about.html
exist, only the first discovered file will be used.
If a discovered file name beings with cmd-
it will be clustered
into a Commands section of the generated index page.
If a discovered file name beings with servlet-
it will be clustered
into a Servlets section of the generated index page.
If a discovered file name beings with rest-api-
it will be clustered
into a REST APIs section of the generated index page.
All other files are clustered under a Documentation section.
Some optional information from the manifest is extracted and displayed as part of the index page, if present in the manifest:
Field | Source Attribute |
---|---|
Name |
Implementation-Title |
Vendor |
Implementation-Vendor |
Version |
Implementation-Version |
URL |
Implementation-URL |
API Version |
Gerrit-ApiVersion |
Deployment
Compiled plugins and extensions can be deployed to a running Gerrit server using the plugin install command.
Plugins can also be copied directly into the server’s
directory at $site_path/plugins/$name.jar
. The name of
the JAR file, minus the .jar
extension, will be used as the
plugin name. Unless disabled, servers periodically scan this
directory for updated plugins. The time can be adjusted by
plugins.checkFrequency.
For disabling plugins the plugin remove command can be used.
Disabled plugins can be re-enabled using the plugin enable command.