Commit bca6c280 authored by Dmitriy Zaporozhets's avatar Dmitriy Zaporozhets

Merge branch 'dz-add-plugins-note-ee' into 'master'

Copyedit plugins docs

See merge request gitlab-org/gitlab-ee!5268
parents 3d2fd170 2ed918bc
...@@ -46,6 +46,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ...@@ -46,6 +46,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- [Uploads configuration](uploads.md): Configure GitLab uploads storage. - [Uploads configuration](uploads.md): Configure GitLab uploads storage.
[source installations](../install/installation.md#installation-from-source). [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. - [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.
- **(Starter/Premium)** [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data. - **(Starter/Premium)** [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data.
- **(Premium)** [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) - **(Premium)** [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md)
......
# Plugins # GitLab Plugin system
**Note:** Plugins must be configured on the filesystem of the GitLab > Introduced in GitLab 10.6.
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. With custom plugins, GitLab administrators can introduce custom integrations
without modifying GitLab's source code.
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:**
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.
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 ## Setup
Plugins must be placed directly into `plugins` directory, subdirectories will be ignored. The plugins must be placed directly into the `plugins` directory, subdirectories
There is an `example` directory inside `plugins` where you can find some basic examples. 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: 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 For an installation from source the path is usually
`/home/git/gitlab/plugins/`. For Omnibus installs the path is `/home/git/gitlab/plugins/`. For Omnibus installs the path is
usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`. 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. 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 1. Write the code to make the plugin function as expected. That can be
in any language. Ensure the 'shebang' at the top properly reflects the language in any language, and ensure the 'shebang' at the top properly reflects the
type. For example, if the script is in Ruby the shebang will probably be language type. For example, if the script is in Ruby the shebang will
`#!/usr/bin/env ruby`. 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. 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 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. 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 If a plugin executes with non-zero exit code or GitLab fails to execute it, a
message will be logged to `plugin.log`. message will be logged to `plugin.log`.
## Validation ## Validation
Writing own plugin can be tricky and its easier if you can check it without altering the system. Writing your own plugin can be tricky and it's easier if you can check it
We provided a rake task you can use with staging environment to test your plugin before using it in production. without altering the system. A rake task is provided so that you can use it
The rake task will use a sample data and execute each of plugins. By output you should be able to determine if in a staging environment to test your plugin before using it in production.
system sees your plugin and if it was executed without errors. 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 ```bash
# Omnibus installations # Omnibus installations
sudo gitlab-rake plugins:validate sudo gitlab-rake plugins:validate
# Installations from source # Installations from source
cd /home/git/gitlab
bundle exec rake plugins:validate RAILS_ENV=production 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 Validating plugins from /plugins directory
* /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code) * /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) * /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 [system hooks]: ../system_hooks/system_hooks.md
[webhooks]: ../user/project/integrations/webhooks.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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment