From 8c9e4d3a9610fba98dc707178bf4a79473429135 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Tue, 27 Feb 2018 16:01:17 +0200 Subject: Add documentation for plugins feature Signed-off-by: Dmitriy Zaporozhets --- doc/administration/plugins.md | 50 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 doc/administration/plugins.md (limited to 'doc/administration/plugins.md') diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md new file mode 100644 index 00000000000..0fea1d2e3ac --- /dev/null +++ b/doc/administration/plugins.md @@ -0,0 +1,50 @@ +# Plugins + +**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. + +Introduced in GitLab 10.6. + +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 asyncronously in case of event. For list of events please see [system hooks] documentation. + +## Setup + +Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. There is an `example` directory insider `plugins` 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. + 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 sepcial characters. +1. Make the hook file executable and make sure it's owned by git. +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`. + +That's it! Assuming the plugin code is properly implemented the hook will fire +as appropriate. Plugins file list is updated on each event. There is no need to restart GitLab to apply a new plugin. + +## 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 enviromnent 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. + +```bash +# Omnibus installations +sudo gitlab-rake plugins:validate + +# Installations from source +bundle exec rake plugins:validate RAILS_ENV=production +``` + + +[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 + -- cgit v1.2.1 From 2150b2cde2700a48095db4364d02f91c9b9a1456 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Tue, 27 Feb 2018 16:02:42 +0200 Subject: [ci skip] Add example of rake plugins:validate output to the doc Signed-off-by: Dmitriy Zaporozhets --- doc/administration/plugins.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/administration/plugins.md') diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index 0fea1d2e3ac..f71cecafb5f 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -41,6 +41,14 @@ sudo gitlab-rake plugins:validate bundle exec rake plugins:validate RAILS_ENV=production ``` +Example of output can be next: + +``` +-> 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 -- cgit v1.2.1 From 4eed9a12216296709306ce29faf607d8aed2a913 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Tue, 27 Feb 2018 18:22:50 +0200 Subject: Fix few typos in plugins doc Signed-off-by: Dmitriy Zaporozhets --- doc/administration/plugins.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/administration/plugins.md') diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index f71cecafb5f..89ab0b9c8ea 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -7,7 +7,7 @@ have filesystem access. Introduced in GitLab 10.6. -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 asyncronously in case of event. For list of events please see [system hooks] documentation. +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. ## Setup @@ -19,7 +19,7 @@ Follow the steps below to set up a custom hook: 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 sepcial characters. +1. Inside the `plugins` directory, create a file with a name of your choice, but without spaces or special characters. 1. Make the hook file executable and make sure it's owned by git. 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 @@ -27,11 +27,11 @@ Follow the steps below to set up a custom hook: `#!/usr/bin/env ruby`. That's it! Assuming the plugin code is properly implemented the hook will fire -as appropriate. Plugins file list is updated on each event. There is no need to restart GitLab to apply a new plugin. +as appropriate. Plugins file list is updated for each event. There is no need to restart GitLab to apply a new plugin. ## 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 enviromnent 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 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. ```bash # Omnibus installations -- cgit v1.2.1 From 2577ff7fd656f301c4b1909f0a1c358c8c30a614 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Wed, 28 Feb 2018 12:16:23 +0200 Subject: Refactor plugins feature and make some doc improvements Signed-off-by: Dmitriy Zaporozhets --- doc/administration/plugins.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/administration/plugins.md') diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index 89ab0b9c8ea..ed1a3480ffc 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -11,7 +11,7 @@ A plugin will run on each event so it's up to you to filter events or projects w ## Setup -Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. There is an `example` directory insider `plugins` where you can find some basic examples. +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. Follow the steps below to set up a custom hook: @@ -20,11 +20,12 @@ Follow the steps below to set up a custom hook: `/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. Make the hook file executable and make sure it's owned by git. +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] 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. -- cgit v1.2.1 From 886d442b405a0db3dccc1b24e050244f65099826 Mon Sep 17 00:00:00 2001 From: Dmitriy Zaporozhets Date: Wed, 28 Feb 2018 12:31:19 +0200 Subject: Improve plugins documentation and remove unnecessary rake task Signed-off-by: Dmitriy Zaporozhets --- doc/administration/plugins.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'doc/administration/plugins.md') diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index ed1a3480ffc..c91ac3012b9 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -11,7 +11,8 @@ A plugin will run on each event so it's up to you to filter events or projects w ## 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. +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. Follow the steps below to set up a custom hook: @@ -30,9 +31,15 @@ Follow the steps below to set up a custom hook: 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. +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 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. ```bash # Omnibus installations -- cgit v1.2.1