From 2d73a0350d9745668d65a53cbcc776f933380f6a Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 15 Apr 2014 08:34:50 -0400 Subject: [PATCH] Documentation --- releases.moxie | 3 +- src/site/plugins_extensions.mkd | 61 ++++++++++++++++++++++++++++++-- src/site/plugins_overview.mkd | 5 +-- src/site/setup_transport_ssh.mkd | 11 ++++-- 4 files changed, 72 insertions(+), 8 deletions(-) diff --git a/releases.moxie b/releases.moxie index 151f9c30..ac3346c5 100644 --- a/releases.moxie +++ b/releases.moxie @@ -49,7 +49,7 @@ r22: { - args4j 2.0.26 - JGit 3.3.1 - Mina SSHD 0.10.1 - - pf4j 0.7.1 + - pf4j 0.8.0 contributors: - James Moger - David Ostrovsky @@ -57,6 +57,7 @@ r22: { - Jeremie Brebec - Tim Ryan - Decebal Suiu + - Eric Myrhe settings: - { name: 'realm.ldap.bindpattern', defaultValue: ' ' } - { name: 'tickets.closeOnPushCommitMessageRegex', defaultValue: '(?:fixes|closes)[\\s-]+#?(\\d+)' } diff --git a/src/site/plugins_extensions.mkd b/src/site/plugins_extensions.mkd index d7469ac6..6e0e52e6 100644 --- a/src/site/plugins_extensions.mkd +++ b/src/site/plugins_extensions.mkd @@ -2,20 +2,56 @@ Gitblit offers several extension points for enhancing and customizing it's runtime behavior. -Each available extension point has a sample implementation in the [gitblit-cookbook-plugin (Maven project)](https://dev.gitblit.com/summary/gitblit-cookbook-plugin.git). +Each available extension point has a sample implementation in the [gitblit-cookbook-plugin (Maven project)](https://github.com/gitblit/gitblit-cookbook-plugin). + +**NOTE:** +Gitblit does not yet offer a comprehensize dependency injection architecture. This will be addressed in a subsequent release. For now you may access all of Gitblit's core managers through a static singleton app context: + +```java +import com.gitblit.extensions.GitblitPlugin; +import com.gitblit.servlet.GitblitContext; +import com.gitblit.manager.IRuntimeManager; +import com.gitblit.manager.IUserManager; +import com.gitblit.manager.IAuthenticationManager; +import com.gitblit.manager.INotificationManager; +import com.gitblit.manager.IRepositoryManager; +import com.gitblit.manager.IProjectManager; +import com.gitblit.manager.IFederationManager; +import com.gitblit.manager.IPluginManager; +import com.gitblit.manager.IGitblit; + +public class ExamplePlugin extends GitblitPlugin { + + @Override + public void start() { + IRuntimeManager runtime = GitblitContext.getManager(IRuntimeManager.class); + IUserManager users = GitblitContext.getManager(IUserManager.class); + IAuthenticationManager auth = GitblitContext.getManager(IAuthenticationManager.class); + INotificationManager notifications = GitblitContext.getManager(INotificationManager.class); + IRepositoryManager repos = GitblitContext.getManager(IRepositoryManager.class); + IProjectManager projects = GitblitContext.getManager(IProjectManager.class); + IFederationManager federation = GitblitContext.getManager(IFederationManager.class); + IPluginManager plugins = GitblitContext.getManager(IPluginManager.class); + IGitblit gitblit = GitblitContext.getManager(IGitblit.class); + } +} +``` ### SSH Dispatch Command *SINCE 1.5.0* -You can provide your own custom SSH commands by subclassing the *DispatchCommand* class. +You can provide your own custom SSH command hierarchies by subclassing the *DispatchCommand* class. ```java import ro.fortsoft.pf4j.Extension; - +import org.kohsuke.args4j.Option; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; import com.gitblit.models.UserModel; import com.gitblit.transport.ssh.commands.CommandMetaData; import com.gitblit.transport.ssh.commands.DispatchCommand; +import com.gitblit.transport.ssh.commands.UsageExample; @Extension @CommandMetaData(name = "mycommands", description = "Sample SSH dispatcher") @@ -31,6 +67,25 @@ public class MyDispatcher extends DispatchCommand { register(user, SubDispatcher1.class); register(user, SubDispatcher2.class); } + + @CommandMetaData(name = "commanda", aliases = { "ca" }, description = "description of command a") + @UsageExample(syntax = "${cmd} --myflag", description = "description of commanda with --myflag") + public static class CommandA extends SshCommand { + + protected final Logger log = LoggerFactory.getLogger(getClass()); + + @Option(name = "--myflag", aliases = { "-m" }, usage = "enable myflag") + boolean myflag; + + @Override + public void run() throws Failure { + if (myflag) { + log.info("Run with --myflag"); + } else { + log.info("Run without --myflag"); + } + } + } } ``` diff --git a/src/site/plugins_overview.mkd b/src/site/plugins_overview.mkd index 5cb60d07..45a54344 100644 --- a/src/site/plugins_overview.mkd +++ b/src/site/plugins_overview.mkd @@ -23,6 +23,7 @@ A plugin defines it's metadata in the META-INF/MANIFEST.MF file: Plugin-Description: Command and control Gitblit over SSH Plugin-Class: com.gitblit.plugin.powertools.Powertools Plugin-Version: 1.2.0 + Plugin-Requires: 1.5.0 Plugin-Provider: gitblit.com 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. @@ -32,9 +33,9 @@ In addition to extending Gitblit core, plugins can also define extension points **NOTE:** 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 Dependencies & Requires +#### Limitations of Dependencies -Plugins may specify dependencies by ID, but may not specify specific versions of a dependency. The plugin registry allows you to specify a *requires* version of Gitblit, but this is not currently enforced. +Plugins may specify dependencies by ID, but may not specify specific versions of a dependency. ### Managing Plugins diff --git a/src/site/setup_transport_ssh.mkd b/src/site/setup_transport_ssh.mkd index a671e5af..7b53624b 100644 --- a/src/site/setup_transport_ssh.mkd +++ b/src/site/setup_transport_ssh.mkd @@ -80,7 +80,14 @@ You can also remove all your public keys from your account. ssh -l -p 29418 keys remove ALL -### SSH Command Plugins +##### keys permission + +You may control the access permission for each SSH key. This is more of a safety feature than a security measure. + +| Permission | Description | +| ---------- | ----------------------------------------------- | +| V | SSH key may not be used for clone/fetch or push | +| R | SSH key may be used to clone/fetch | +| RW | SSH key may be used to clone/fetch and push | -Gitblit supports loading custom SSH command plugins. -- 2.39.5