diff options
Diffstat (limited to 'doc/administration/server_hooks.md')
| -rw-r--r-- | doc/administration/server_hooks.md | 192 |
1 files changed, 78 insertions, 114 deletions
diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 2a431d17774..9d8bc03e5e9 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -10,171 +10,135 @@ disqus_identifier: 'https://docs.gitlab.com/ee/administration/custom_hooks.html' > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196051) in GitLab 12.8 replacing Custom Hooks. -Git supports hooks that are executed on different actions. These hooks run on the server and can be -used to enforce specific commit policies or perform other tasks based on the state of the -repository. +Server hooks run custom logic on the GitLab server. Users can use them to run Git-related tasks such as: -Git supports the following hooks: +- Enforcing specific commit policies. +- Performing tasks based on the state of the repository. -- `pre-receive` -- `post-receive` -- `update` +Server hooks use `pre-receive`, `post-receive`, and `update` +[Git server-side hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_server_side_hooks). -See [the Git documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_server_side_hooks) -for more information about each hook type. +GitLab administrators configure server hooks on the file system of the GitLab server. If you don't have file system access, +alternatives to server hooks include: -Server-side Git hooks can be configured for: +- [Webhooks](../user/project/integrations/webhooks.md). +- [GitLab CI/CD](../ci/index.md). +- [Push rules](../push_rules/push_rules.md), for a user-configurable Git hook interface. -- [A single repository](#create-a-server-hook-for-a-repository). -- [All repositories](#create-a-global-server-hook-for-all-repositories). +[Geo](geo/index.md) doesn't replicate server hooks to secondary nodes. -Note the following about server hooks: +## Create a server hook for a single repository -- Server hooks must be configured on the file system of the GitLab server. Only GitLab server - administrators are able to complete these tasks. If you don't have file system access, see - possible alternatives such as: - - [Webhooks](../user/project/integrations/webhooks.md). - - [GitLab CI/CD](../ci/index.md). - - [Push Rules](../push_rules/push_rules.md), for a user-configurable Git hook - interface. -- Server hooks aren't replicated to [Geo](geo/index.md) secondary nodes. +To create a server hook for a single repository: -## Create a server hook for a repository +1. On the top bar, select **Menu > Admin**. +1. Go to **Overview > Projects** and select the project you want to add a server hook to. +1. On the page that appears, locate the value of **Gitaly relative path**. This path is where server hooks must be located. + - If you are using [hashed storage](repository_storage_types.md#hashed-storage), see + [Translate hashed storage paths](repository_storage_types.md#translate-hashed-storage-paths) for information on + interpreting the relative path. + - If you are not using [hashed storage](repository_storage_types.md#hashed-storage): + - For Omnibus GitLab installations, the path is usually `/var/opt/gitlab/git-data/repositories/<group>/<project>.git`. + - For an installation from source, the path is usually `/home/git/repositories/<group>/<project>.git`. +1. On the file system, create a new directory in the correct location called `custom_hooks`. +1. In the new `custom_hooks` directory, create a file with a name that matches the hook type. For example, for a + `pre-receive` server hook, the filename should be `pre-receive` with no extension. +1. Make the server hook file executable and ensure that it's owned by the Git user. +1. Write the code to make the server hook function as expected. Server hooks can be in any programming language. Ensure + the [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top reflects the language type. For + example, if the script is in Ruby the shebang is probably `#!/usr/bin/env ruby`. -If you are not using [hashed storage](repository_storage_types.md#hashed-storage), the project's -repository directory might not exactly match the instructions below. In that case: - -- For an installation from source, the path is usually - `/home/git/repositories/<group>/<project>.git`. -- For Omnibus GitLab installs, the path is usually - `/var/opt/gitlab/git-data/repositories/<group>/<project>.git`. - -Follow the steps below to set up a server-side hook for a repository: - -1. Go to **Admin area > Projects** and select the project you want to add a server hook to. -1. Locate the **Gitaly relative path** on the page that appears. This is where the server hook - must be implemented. For information on interpreting the relative path, see - [Translate hashed storage paths](repository_storage_types.md#translate-hashed-storage-paths). -1. On the file system, create a new directory in this location called `custom_hooks`. -1. Inside the new `custom_hooks` directory, create a file with a name matching the hook type. For - example, for a pre-receive hook the filename should be `pre-receive` with no extension. -1. Make the hook file executable and ensure that it's owned by the Git user. -1. Write the code to make the server hook function as expected. Hooks can be in any language. Ensure - the ["shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top properly reflects the - language type. For example, if the script is in Ruby the shebang is probably - `#!/usr/bin/env ruby`. - -Assuming the hook code is properly implemented, the hook code is executed as appropriate. +If the server hook code is properly implemented, it should execute when the Git hook is next triggered. ## Create a global server hook for all repositories -To create a Git hook that applies to all of the repositories in your instance, set a global server -hook. The default global server hook directory is in the GitLab Shell directory. Any -hook added there applies to all repositories, including: +To create a Git hook that applies to all repositories, set a global server hook. The default global server hook directory +is in the GitLab Shell directory. Any server hook added there applies to all repositories, including: + +- [Project and group wiki](../user/project/wiki/index.md) repositories. Their storage directory names are in the format + `<id>.wiki.git`. +- [Design management](../user/project/issues/design_management.md) repositories under a project. Their storage directory + names are in the format `<id>.design.git`. -- [Project and group wiki](../user/project/wiki/index.md) repositories, - whose storage directory names are in the format `<id>.wiki.git`. -- [Design management](../user/project/issues/design_management.md) repositories under a - project, whose storage directory names are in the format `<id>.design.git`. +### Choose a server hook directory -The default directory: +Before creating a global server hook, you must choose a directory for it. The default global server hook directory: +- For Omnibus GitLab installations is usually `/opt/gitlab/embedded/service/gitlab-shell/hooks`. - For an installation from source is usually `/home/git/gitlab-shell/hooks`. -- For Omnibus GitLab installs is usually `/opt/gitlab/embedded/service/gitlab-shell/hooks`. -To use a different directory for global server hooks, set `custom_hooks_dir` in Gitaly -configuration: +To use a different directory for global server hooks, set `custom_hooks_dir` in Gitaly configuration: -- For Omnibus installations, this is set in `gitlab.rb`. +- For Omnibus installations, set in `gitlab.rb`. - For source installations, the configuration location depends on the GitLab version. For: - - GitLab 13.0 and earlier, this is set in `gitlab-shell/config.yml`. - - GitLab 13.1 and later, this is set in `gitaly/config.toml` under the `[hooks]` section. - -NOTE: -The `custom_hooks_dir` value in `gitlab-shell/config.yml` is still honored in GitLab 13.1 and later -if the value in `gitaly/config.toml` is blank or non-existent. + - GitLab 13.0 and earlier, set in `gitlab-shell/config.yml`. + - GitLab 13.1 and later, set in `gitaly/config.toml` under the `[hooks]` section. However, GitLab honors the + `custom_hooks_dir` value in `gitlab-shell/config.yml` if the value in `gitaly/config.toml` is blank or non-existent. -Follow the steps below to set up a global server hook for all repositories: +### Create the global server hook -1. On the GitLab server, navigate to the configured global server hook directory. -1. Create a new directory in this location. Depending on the type of hook, it can be either a - `pre-receive.d`, `post-receive.d`, or `update.d` directory. -1. Inside this new directory, add your hook. Hooks can be in any language. Ensure the - ["shebang"](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top properly reflects the - language type. For example, if the script is in Ruby the shebang is probably - `#!/usr/bin/env ruby`. -1. Make the hook file executable and ensure that it's owned by the Git user. +To create a global server hook for all repositories: -Now test the hook to check whether it is functioning properly. +1. On the GitLab server, go to the configured global server hook directory. +1. Create a new directory in this location called `pre-receive.d`, `post-receive.d`, or `update.d`, depending on the type + of server hook. Any other names are ignored. +1. Inside this new directory, add your server hook. Server hooks can be in any programming language. Ensure the + [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top reflects the language type. For example, if the + script is in Ruby the shebang is probably `#!/usr/bin/env ruby`. +1. Make the hook file executable, ensure that it's owned by the Git user, and ensure it does not match the backup file + pattern (`*~`). -## Chained hooks +If the server hook code is properly implemented, it should execute when the Git hook is next triggered. -Server hooks set [per project](#create-a-server-hook-for-a-repository) or -[globally](#create-a-global-server-hook-for-all-repositories) can be executed in a chain. +## Chained server hooks -Server hooks are searched for and executed in the following order of priority: +GitLab can execute server hooks in a chain. GitLab searches for and executes server hooks in the following order: -- Built-in GitLab server hooks. These are not user-customizable. -- `<project>.git/custom_hooks/<hook_name>`: Per-project hooks. This was kept for backwards - compatibility. +- Built-in GitLab server hooks. These server hooks are not customizable by users. +- `<project>.git/custom_hooks/<hook_name>`: Per-project hooks. This location is kept for backwards compatibility. - `<project>.git/custom_hooks/<hook_name>.d/*`: Location for per-project hooks. -- `<custom_hooks_dir>/<hook_name>.d/*`: Location for all executable global hook files - except editor backup files. +- `<custom_hooks_dir>/<hook_name>.d/*`: Location for all executable global hook files except editor backup files. -Within a directory, server hooks: +Within a server hooks directory, hooks: - Are executed in alphabetical order. - Stop executing when a hook exits with a non-zero value. -`<hook_name>.d` must be either `pre-receive.d`, `post-receive.d`, or `update.d` to work properly. -Any other names are ignored. +## Environment variables available to server hooks -Files in `.d` directories must be executable and not match the backup file pattern (`*~`). +You can pass any environment variable to server hooks, but you should only rely on supported environment variables. -For `<project>.git` you need to [translate](repository_storage_types.md#translate-hashed-storage-paths) -your project name into the hashed storage format that GitLab uses. +The following GitLab environment variables are supported for all server hooks: -## Environment Variables +| Environment variable | Description | +|:---------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `GL_ID` | GitLab identifier of user that initiated the push. For example, `user-2234`. | +| `GL_PROJECT_PATH` | (GitLab 13.2 and later) GitLab project path. | +| `GL_PROTOCOL` | (GitLab 13.2 and later) Protocol used for this change. One of: `http` (Git `push` using HTTP), `ssh` (Git `push` using SSH), or `web` (all other actions). | +| `GL_REPOSITORY` | `project-<id>` where `id` is the ID of the project. | +| `GL_USERNAME` | GitLab username of the user that initiated the push. | -The following set of environment variables are available to server hooks. - -| Environment variable | Description | -|:---------------------|:----------------------------------------------------------------------------| -| `GL_ID` | GitLab identifier of user that initiated the push. For example, `user-2234` | -| `GL_PROJECT_PATH` | (GitLab 13.2 and later) GitLab project path | -| `GL_PROTOCOL` | (GitLab 13.2 and later) Protocol used for this change. One of: `http` (Git Push using HTTP), `ssh` (Git Push using SSH), or `web` (all other actions). | -| `GL_REPOSITORY` | `project-<id>` where `id` is the ID of the project | -| `GL_USERNAME` | GitLab username of the user that initiated the push | - -Pre-receive and post-receive server hooks can also access the following Git environment variables. +The following Git environment variables are supported for `pre-receive` and `post-receive` server hooks: | Environment variable | Description | |:-----------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `GIT_ALTERNATE_OBJECT_DIRECTORIES` | Alternate object directories in the quarantine environment. See [Git `receive-pack` documentation](https://git-scm.com/docs/git-receive-pack#_quarantine_environment). | | `GIT_OBJECT_DIRECTORY` | GitLab project path in the quarantine environment. See [Git `receive-pack` documentation](https://git-scm.com/docs/git-receive-pack#_quarantine_environment). | -| `GIT_PUSH_OPTION_COUNT` | Number of push options. See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | -| `GIT_PUSH_OPTION_<i>` | Value of push options where `i` is from `0` to `GIT_PUSH_OPTION_COUNT - 1`. See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | - -NOTE: -While other environment variables can be passed to server hooks, your application should not rely on -them as they can change. +| `GIT_PUSH_OPTION_COUNT` | Number of [push options](../user/project/push_options.md). See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | +| `GIT_PUSH_OPTION_<i>` | Value of [push options](../user/project/push_options.md) where `i` is from `0` to `GIT_PUSH_OPTION_COUNT - 1`. See [Git `pre-receive` documentation](https://git-scm.com/docs/githooks#pre-receive). | ## Custom error messages -To have custom error messages appear in the GitLab UI when a commit is declined or an error occurs -during the Git hook, your script should: +You can have custom error messages appear in the GitLab UI when a commit is declined or an error occurs during the Git +hook. To display a custom error message, your script must: - Send the custom error messages to either the script's `stdout` or `stderr`. - Prefix each message with `GL-HOOK-ERR:` with no characters appearing before the prefix. -### Example custom error message - -This hook script written in Bash generates the following message in the GitLab UI: +For example: ```shell #!/bin/sh echo "GL-HOOK-ERR: My custom error message."; exit 1 ``` - - |