Skip to content

GitLab Plugin system

Introduced in GitLab 10.6.

With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code.

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. Exploresystem hooksorwebhooksas an option if you do not have filesystem access.

插件将运行在每个事件这是取决于你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 thesystem hooksdocumentation.

Setup

The plugins must be placed directly into thepluginsdirectory, subdirectories will be ignored. There is anexampledirectory insidepluginswhere you can find some basic examples.

Follow the steps below to set up a custom hook:

  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.

    Forhighly availableconfigurations, your hook file should exist on each application server.

  2. Inside thepluginsdirectory, create a file with a name of your choice, without spaces or special characters.

  3. Make the hook file executable and make sure it's owned by the git user.

  4. 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.

  5. The data to the plugin will be provided as JSON on STDIN. It will be exactly same as forsystem hooks

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 toplugin.log.

Validation

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.

# Omnibus installationssudogitlab-rake plugins:validate# Installations from sourcecd/home/git/gitlabbundleexecrake plugins:validateRAILS_ENV=production

Example of output:

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)
Baidu
map