debian-mirror-gitlab/doc/administration/file_hooks.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

120 lines
4.7 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
2023-03-04 22:38:38 +05:30
stage: Manage
group: Integrations
2022-11-25 23:54:43 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference
---
2021-04-17 20:07:23 +05:30
# File hooks **(FREE SELF)**
2020-03-13 15:44:24 +05:30
2023-01-13 00:05:48 +05:30
Use custom file hooks (not to be confused with [server hooks](server_hooks.md) or [system hooks](system_hooks.md)),
to introduce custom integrations without modifying the GitLab source code.
2020-03-13 15:44:24 +05:30
2021-11-18 22:05:49 +05:30
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
2022-06-21 17:19:12 +05:30
see the [system hooks](system_hooks.md) documentation.
2020-03-13 15:44:24 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-03-11 19:13:27 +05:30
File hooks must be configured on the file system of the GitLab server. Only GitLab
server administrators can complete these tasks. Explore
2022-06-21 17:19:12 +05:30
[system hooks](system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md)
2021-03-11 19:13:27 +05:30
as an option if you do not have file system access.
2021-11-18 22:05:49 +05:30
Instead of writing and supporting your own file hook, you can also make changes
directly to the GitLab source code and contribute back upstream. In this way, we can
ensure functionality is preserved across versions and covered by tests.
2020-03-13 15:44:24 +05:30
## Setup
2020-04-22 19:07:51 +05:30
The file hooks must be placed directly into the `file_hooks` directory, subdirectories
2021-03-11 19:13:27 +05:30
are ignored. There is an
2021-09-04 01:27:46 +05:30
[`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/file_hooks/examples)
2020-03-13 15:44:24 +05:30
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 plugin directory.
For an installation from source the path is usually
2020-04-22 19:07:51 +05:30
`/home/git/gitlab/file_hooks/`. For Omnibus installs the path is
usually `/opt/gitlab/embedded/service/gitlab-rails/file_hooks`.
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
For [configurations with multiple servers](reference_architectures/index.md),
your hook file should exist on each application server.
2020-03-13 15:44:24 +05:30
2020-04-22 19:07:51 +05:30
1. Inside the `file_hooks` directory, create a file with a name of your choice,
2020-03-13 15:44:24 +05:30
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 file hook 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`.
2022-07-23 23:45:48 +05:30
1. The data to the file hook is provided as JSON on `STDIN`. It is exactly the
2022-06-21 17:19:12 +05:30
same as for [system hooks](system_hooks.md).
2020-03-13 15:44:24 +05:30
2021-03-11 19:13:27 +05:30
That's it! Assuming the file hook code is properly implemented, the hook fires
2020-03-13 15:44:24 +05:30
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
2021-03-11 19:13:27 +05:30
message is logged to:
2020-03-13 15:44:24 +05:30
2021-09-04 01:27:46 +05:30
- `gitlab-rails/file_hook.log` in an Omnibus installation.
- `log/file_hook.log` in a source installation.
NOTE:
2021-11-18 22:05:49 +05:30
In GitLab 13.12 and earlier, the filename was `plugin.log`
2020-03-13 15:44:24 +05:30
## Creating file hooks
2021-03-11 19:13:27 +05:30
This example responds only on the event `project_create`, and
the GitLab instance informs the administrators that a new project has been created.
2020-03-13 15:44:24 +05:30
```ruby
2020-11-24 15:15:51 +05:30
#!/opt/gitlab/embedded/bin/ruby
2020-03-13 15:44:24 +05:30
# By using the embedded ruby version we eliminate the possibility that our chosen language
# would be unavailable from
require 'json'
require 'mail'
# The incoming variables are in JSON format so we need to parse it first.
2021-09-04 01:27:46 +05:30
ARGS = JSON.parse($stdin.read)
2020-03-13 15:44:24 +05:30
# We only want to trigger this file hook on the event project_create
return unless ARGS['event_name'] == 'project_create'
# We will inform our admins of our gitlab instance that a new project is created
Mail.deliver do
from 'info@gitlab_instance.com'
to 'admin@gitlab_instance.com'
subject "new project " + ARGS['name']
body ARGS['owner_name'] + 'created project ' + ARGS['name']
end
```
## Validation
Writing your own file hook can be tricky and it's easier if you can check it
2020-04-22 19:07:51 +05:30
without altering the system. A Rake task is provided so that you can use it
2020-03-13 15:44:24 +05:30
in a staging environment to test your file hook before using it in production.
2021-03-11 19:13:27 +05:30
The Rake task uses a sample data and execute each of file hook. The output
2020-03-13 15:44:24 +05:30
should be enough to determine if the system sees your file hook and if it was
executed without errors.
```shell
# Omnibus installations
sudo gitlab-rake file_hooks:validate
# Installations from source
cd /home/git/gitlab
bundle exec rake file_hooks:validate RAILS_ENV=production
```
Example of output:
```plaintext
2020-04-22 19:07:51 +05:30
Validating file hooks from /file_hooks directory
* /home/git/gitlab/file_hooks/save_to_file.clj succeed (zero exit code)
* /home/git/gitlab/file_hooks/save_to_file.rb failure (non-zero exit code)
2020-03-13 15:44:24 +05:30
```