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
|
- [GitLab Pages configuration for GitLab source installations](pages/source.md): Enable and configure GitLab Pages on
|
||||||
[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.
|
||||||
|
|
||||||
#### Customizing GitLab's appearance
|
#### Customizing GitLab's appearance
|
||||||
|
|
||||||
|
|
|
@ -1,66 +1,80 @@
|
||||||
# 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
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue