|
| 1 | +# Plugins |
| 2 | +Git Proxy has a simple mechanism for exposing customization within the application for organizations who wish to augment Git Proxy's built-in features, add custom functionality or integrate Git Proxy & other systems within their environment. Plugins are authored via custom objects & functions in JavaScript and can be distributed as NPM packages or source files. Plugins are loaded at deployment via configuration of the git-proxy application server. |
| 3 | + |
| 4 | +## Loading plugins |
| 5 | +In order to load a plugin, you must either install the plugin as a standalone npm package by adding the plugin as a dependency or specify a file path on disk to load a `.js` file as a module. |
| 6 | + |
| 7 | +### NPM |
| 8 | +1. Add the plugin package as a dependency. |
| 9 | +```json |
| 10 | +{ |
| 11 | + "name": "@finos/git-proxy", |
| 12 | + ... |
| 13 | + "dependencies: { |
| 14 | + "foo-my-gitproxy-plugin": "^0.0.1", |
| 15 | + "@bar/another-gitproxy-plugin": "^0.0.1", |
| 16 | + } |
| 17 | +} |
| 18 | +``` |
| 19 | + |
| 20 | +2. Set the "pushPlugins" property in proxy.config.json to a list of modules to load into Git Proxy. These packages must exist in `node_modules/`. |
| 21 | + |
| 22 | +```json |
| 23 | +{ |
| 24 | + "pushPlugins": [ |
| 25 | + "foo-my-gitproxyplugin", |
| 26 | + "@bar/another-gitproxy-plugin" |
| 27 | + ] |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +### Local files |
| 32 | +1. Download the plugin's source files & run `npm install` to download any dependencies of the plugin itself. |
| 33 | +2. Set the "pushPlugins" property in proxy.config.json to a list of files to load into Git Proxy. |
| 34 | +```json |
| 35 | +{ |
| 36 | + "pushPlugins": [ |
| 37 | + "./plugins/foo/index.js", |
| 38 | + "/home/alice/gitproxy-push-plugin/index.js" |
| 39 | + ] |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +### Environment variables (deprecated) |
| 44 | +The previous implementation of plugins were loaded via the following two environment variables: |
| 45 | + |
| 46 | +- `GITPROXY_PLUGIN_FILES`: a list of comma-separated JavaScript files which point to Node modules that contain plugin objects |
| 47 | +- `GITPROXY_PLUGIN_PACKAGES`: a list of comma-separated NPM packages which contain modules & plugin objects |
| 48 | + |
| 49 | +Any files or packages specified by these variables will continue to be loaded via the plugin loader if set. However, it is recommended to simply list either files or NPM packages to load as plugins via configuration as documented above. These environment variables will be removed in a future release. |
| 50 | + |
| 51 | +```bash |
| 52 | +# Setting a list of plugin packages to load via env var when running git-proxy |
| 53 | +$ export GITPROXY_PLUGIN_PACKAGES="foo-my-gitproxyplugin,@bar/another-gitproxy-plugin/src/plugins/baz" |
| 54 | +$ npx -- @finos/git-proxy |
| 55 | +``` |
| 56 | + |
| 57 | +## Writing plugins |
| 58 | +Plugins are written as Node modules which export objects containing the custom behaviour. These objects must extend the classes exported by Git Proxy's `plugin/` module. The only class which is exported today for developers to extend Git Proxy is called the `PushActionPlugin` class. This class executes the custom behaviour on any `git push` going through Git Proxy. |
| 59 | + |
| 60 | +The `PushActionPlugin` class takes a single function into its constructor which is executed on a `git push`. This is then loaded into the push proxy's "chain" of actions. Custom plugins are executed after parsing of a push but before any builtin actions. It is important to be aware of the load order when writing plugins to ensure that one plugin does not conflict with another. The order specified in `pushPlugins` configuration setting is preserved by the loader. |
| 61 | + |
| 62 | +To write a custom plugin, import the `PushActionPlugin` class from `@finos/git-proxy` and create a new type with your custom function: |
| 63 | + |
| 64 | +```javascript |
| 65 | +// plugin-foo/index.js |
| 66 | +const PushActionPlugin = require('@finos/git-proxy/src/plugin').PushActionPlugin; |
| 67 | + |
| 68 | +class MyPlugin extends PushActionPlugin { |
| 69 | + constructor() { |
| 70 | + super((req, action) => { |
| 71 | + console.log(req); // Log the express.Request object |
| 72 | + // insert custom behaviour here using the Action object... |
| 73 | + return action; |
| 74 | + }) |
| 75 | + } |
| 76 | +} |
| 77 | + |
| 78 | +module.exports = new MyPlugin(); |
| 79 | +``` |
| 80 | + |
| 81 | +> Note: use `peerDependencies` to depend on `@finos/git-proxy` in your plugin's package to avoid circular dependencies! |
| 82 | +
|
| 83 | +## Sample plugin |
| 84 | +Git Proxy includes a sample plugin that can be loaded with any deployment for demonstration purposes. This plugin is not published as a standalone NPM package and must be used as a local file during deployment. To use the sample plugin: |
| 85 | + |
| 86 | +1. Run `npm install` in [./plugins/git-proxy-hello-world](./git-proxy-hello-world/). |
| 87 | +2. Set "pushPlugins" in `proxy.config.json`: |
| 88 | +```json |
| 89 | +{ |
| 90 | + "pushPlugins": [ |
| 91 | + "./plugins/git-proxy-hello-world/index.js" |
| 92 | + ] |
| 93 | +} |
| 94 | +``` |
| 95 | +3. Run Git Proxy from source: |
| 96 | +``` |
| 97 | +npm run start |
| 98 | +``` |
0 commit comments