diff options
Diffstat (limited to 'doc/administration/file_hooks.md')
| -rw-r--r-- | doc/administration/file_hooks.md | 29 |
1 files changed, 15 insertions, 14 deletions
diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index 5de2e4aec3f..cfaeda546cc 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -19,19 +19,20 @@ 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: -File hooks must be configured on the filesystem of the GitLab server. Only GitLab -server administrators will be able to complete these tasks. Explore -[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) as an option if you do not have filesystem access. - -A file hook will run on each event so it's up to you to filter events or projects -within a file hook code. You can have as many file hooks as you want. Each file hook will -be triggered by GitLab asynchronously in case of an event. For a list of events +File hooks must be configured on the file system of the GitLab server. Only GitLab +server administrators can complete these tasks. Explore +[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) +as an option if you do not have file system access. + +A file hook runs on each event. You can filter events or projects +in a file hook's code, and create many file hooks as you need. Each file hook is +triggered by GitLab asynchronously in case of an event. For a list of events see the [system hooks](../system_hooks/system_hooks.md) documentation. ## Setup The file hooks must be placed directly into the `file_hooks` directory, subdirectories -will be ignored. There is an +are ignored. There is an [`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples) where you can find some basic examples. @@ -52,23 +53,23 @@ Follow the steps below to set up a custom hook: 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 file hook will be provided as JSON on STDIN. It will be exactly +1. The data to the file hook is provided as JSON on STDIN. It is exactly the same as for [system hooks](../system_hooks/system_hooks.md). -That's it! Assuming the file hook code is properly implemented, the hook will fire +That's it! Assuming the file hook code is properly implemented, the hook fires as appropriate. The file hooks file list is updated for each event, there is no need to restart GitLab to apply a new file hook. If a file hook executes with non-zero exit code or GitLab fails to execute it, a -message will be logged to: +message is logged to: - `gitlab-rails/plugin.log` in an Omnibus installation. - `log/plugin.log` in a source installation. ## Creating file hooks -Below is an example that will only response on the event `project_create` and -will inform the admins from the GitLab instance that a new project has been created. +This example responds only on the event `project_create`, and +the GitLab instance informs the administrators that a new project has been created. ```ruby #!/opt/gitlab/embedded/bin/ruby @@ -97,7 +98,7 @@ end Writing your own file hook 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 file hook before using it in production. -The Rake task will use a sample data and execute each of file hook. The output +The Rake task uses a sample data and execute each of file hook. The output should be enough to determine if the system sees your file hook and if it was executed without errors. |