diff options
author | Achilleas Pipinellis <axil@gitlab.com> | 2018-04-06 15:20:38 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2018-04-06 15:20:38 +0300 |
commit | c6d80dec764b3029ff86385b92f2042f9b0c82fd (patch) | |
tree | fc0b73dc380a23d62bf689342f19992ea9a352e7 | |
parent | bf54baa73bb648be3e13a74c14641e3916b54269 (diff) |
Copyedit plugins docs
[ci skip]
-rw-r--r-- | doc/administration/index.md | 1 | ||||
-rw-r--r-- | doc/administration/plugins.md | 72 |
2 files changed, 42 insertions, 31 deletions
diff --git a/doc/administration/index.md b/doc/administration/index.md index c8f27719ce9..0906821d6a3 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -39,6 +39,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [GitLab Pages configuration for GitLab source installations](pages/source.md): Enable and configure GitLab Pages on [source installations](../install/installation.md#installation-from-source). - [Environment variables](environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab. +- [Plugins](plugins.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. #### Customizing GitLab's appearance diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index dedb1f913d7..3ae41638ac3 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -1,70 +1,80 @@ -# Plugins +# GitLab Plugin system -**Note:** Instead of writing and supporting your own plugin you can make changes -directly to the GitLab source code and contribute it back to the upstream. This way we can -ensure functionality is preserved across versions and covered by tests. +> Introduced in GitLab 10.6. -**Note:** Plugins must be configured on the filesystem of the GitLab -server. Only GitLab server administrators will be able to complete these tasks. -Please explore [system hooks] or [webhooks] as an option if you do not -have filesystem access. +With custom plugins, GitLab administrators can introduce custom integrations +without modifying GitLab's source code. -Introduced in GitLab 10.6. +NOTE: **Note:** +Instead of writing and supporting your own plugin you can make changes +directly to the GitLab source code and contribute back upstream. This way we can +ensure functionality is preserved across versions and covered by tests. -A plugin will run on each event so it's up to you to filter events or projects within a plugin code. You can have as many plugins as you want. Each plugin will be triggered by GitLab asynchronously in case of an event. For a list of events please see [system hooks] documentation. +NOTE: **Note:** +Plugins must be configured on the filesystem of the GitLab server. Only GitLab +server administrators will be able to complete these tasks. Explore +[system hooks] or [webhooks] as an option if you do not have filesystem access. + +A plugin will run on each event so it's up to you to filter events or projects +within a plugin code. You can have as many plugins as you want. Each plugin will +be triggered by GitLab asynchronously in case of an event. For a list of events +see the [system hooks] documentation. ## Setup -Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. -There is an `example` directory inside `plugins` where you can find some basic examples. +The plugins must be placed directly into the `plugins` directory, subdirectories +will be ignored. There is an +[`example` directory inside `plugins`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/plugins/examples) +where you can find some basic examples. Follow the steps below to set up a custom hook: -1. On the GitLab server, navigate to the project's plugin directory. +1. On the GitLab server, navigate to the plugin directory. For an installation from source the path is usually `/home/git/gitlab/plugins/`. For Omnibus installs the path is usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`. -1. Inside the `plugins` directory, create a file with a name of your choice, but without spaces or special characters. +1. Inside the `plugins` directory, create a file with a name of your choice, + without spaces or special characters. 1. Make the hook file executable and make sure it's owned by the git user. -1. Write the code to make the plugin function as expected. Plugin can be - in any language. Ensure the 'shebang' at the top properly reflects the language - type. For example, if the script is in Ruby the shebang will probably be - `#!/usr/bin/env ruby`. -1. The data to the plugin will be provided as JSON on STDIN. It will be exactly same as one for [system hooks] +1. Write the code to make the plugin function as expected. That can be + in any language, and ensure the 'shebang' at the top properly reflects the + language type. For example, if the script is in Ruby the shebang will + probably be `#!/usr/bin/env ruby`. +1. The data to the plugin will be provided as JSON on STDIN. It will be exactly + same as for [system hooks] -That's it! Assuming the plugin code is properly implemented the hook will fire -as appropriate. Plugins file list is updated for each event. There is no need to restart GitLab to apply a new plugin. +That's it! Assuming the plugin code is properly implemented, the hook will fire +as appropriate. The plugins file list is updated for each event, there is no +need to restart GitLab to apply a new plugin. If a plugin executes with non-zero exit code or GitLab fails to execute it, a message will be logged to `plugin.log`. ## Validation -Writing own plugin can be tricky and its easier if you can check it without altering the system. -We provided a rake task you can use with staging environment to test your plugin before using it in production. -The rake task will use a sample data and execute each of plugins. By output you should be able to determine if -system sees your plugin and if it was executed without errors. +Writing your own plugin can be tricky and it's easier if you can check it +without altering the system. A rake task is provided so that you can use it +in a staging environment to test your plugin before using it in production. +The rake task will use a sample data and execute each of plugin. The output +should be enough to determine if the system sees your plugin and if it was +executed without errors. ```bash # Omnibus installations sudo gitlab-rake plugins:validate # Installations from source +cd /home/git/gitlab bundle exec rake plugins:validate RAILS_ENV=production ``` -Example of output can be next: +Example of output: ``` --> bundle exec rake plugins:validate RAILS_ENV=production Validating plugins from /plugins directory * /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code) * /home/git/gitlab/plugins/save_to_file.rb failure (non-zero exit code) ``` -[hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks [system hooks]: ../system_hooks/system_hooks.md [webhooks]: ../user/project/integrations/webhooks.md -[5073]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5073 -[93]: https://gitlab.com/gitlab-org/gitlab-shell/merge_requests/93 - |