Merge branch 'dz-add-plugins-note' into 'master'
Add a note to plugins.md about contributing back to GitLab See merge request gitlab-org/gitlab-ce!18215
This commit is contained in:
commit
cf9a8cda56
|
@ -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
|
||||
|
||||
|
|
|
@ -1,66 +1,80 @@
|
|||
# Plugins
|
||||
# GitLab Plugin system
|
||||
|
||||
**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.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
|
|
Loading…
Reference in New Issue