From c58f93d08c6848a373dbba24689be3560fad924a Mon Sep 17 00:00:00 2001 From: John Cai Date: Fri, 10 Jun 2022 12:41:22 -0400 Subject: gitaly-hooks: Update README.md Clarify the story of how `gitaly-hooks` is invoked through being symlinked from `post-receive`, `pre-receive`, `update`, `reference-transaction`. Add section on `reference-transaction` hook. Update some outdated code references. --- cmd/gitaly-hooks/README.md | 41 +---------------------------------------- doc/hooks.md | 24 ++++++++++++++++++++++-- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/cmd/gitaly-hooks/README.md b/cmd/gitaly-hooks/README.md index 629cebbd0..715a2566a 100644 --- a/cmd/gitaly-hooks/README.md +++ b/cmd/gitaly-hooks/README.md @@ -1,42 +1,3 @@ # gitaly-hooks -`gitaly-hooks` is a binary that is the single point of entry for git hooks through gitaly. - -## How is it invoked? - -`gitaly-hooks` has the following subcommands: - -| subcommand | purpose | arguments | stdin | -|--------------|-------------------------------------------------|--------------------------------------|---------------------------------------------| -| `check` | checks if the hooks can reach the gitlab server | none | none | -| `pre-receive` | used as the git pre-receive hook | none | `` SP `` SP `` LF | -| `update` | used as the git update hook | `` `` `` | none -| `post-receive` | used as the git post-receive hook | none | `` SP `` SP `` LF | -| `git` | used as the git pack-objects hook | `pack-objects` `[--stdout]` `[--shallow-file]` | `` | - -## Where is it invoked from? - -There are three main code paths that call `gitaly-hooks`. - -### git receive-pack (SSH & HTTP) - -We have two RPCs that perform the `git receive-pack` function, [SSHReceivePack](https://gitlab.com/gitlab-org/gitaly/-/blob/master/internal/service/ssh/receive_pack.go) and [PostReceivePack](https://gitlab.com/gitlab-org/gitaly/-/blob/master/internal/service/smarthttp/receive_pack.go). - -Both of these RPCs, when executing `git receive-pack`, set `core.hooksPath` to the path of the `gitaly-hooks` binary. [That happens here in `ReceivePackConfig`](https://gitlab.com/gitlab-org/gitaly/-/blob/master/internal/git/receivepack.go). - -### Operations service RPCs - -In the [operations service](https://gitlab.com/gitlab-org/gitaly/-/tree/master/internal/service/operations) there are RPCs that call out to `gitaly-ruby`, which then do certain operations that execute git hooks. -This is accomplished through the `with_hooks` method [here](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/lib/gitlab/git/operation_service.rb). Eventually the [`hook.rb`](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/lib/gitlab/git/hook.rb) is -called, which then calls the `gitaly-hooks` binary. This method doesn't rely on git to run the hooks. Instead, the arguments and input to the -hooks are built in ruby and then get shelled out to `gitaly-hooks`. - -### git upload-pack (SSH & HTTP) - -Only when the pack-objects cache is enabled in Gitaly's configuration file. - -SSHUploadPack and PostUploadPack, when executing `git upload-pack`, set `uploadpack.packObjectsHook` to the path of the `gitaly-hooks` binary. Afterward, when `git upload-pack` requests packfile data, it calls `gitaly-hooks` binary instead of `git pack-objects`. [That happens here in `WithPackObjectsHookEnv`](https://gitlab.com/gitlab-org/gitaly/-/blob/47164700a1ea086c5e8ca0d02feefe4e68bf4f81/internal/git/hooks_options.go#L54) - -## What does gitaly-hooks do? - -`gitaly-hooks` will take the arguments and make an RPC call to `PreReceiveHook`, `UpdateHook`, `PostReceiveHook`, or `PackObjectsHook` accordingly. +See the [hooks documentation](../../doc/hooks.md) for how `gitaly-hooks` fits into Gitaly. diff --git a/doc/hooks.md b/doc/hooks.md index e1afd7bdf..232273587 100644 --- a/doc/hooks.md +++ b/doc/hooks.md @@ -36,12 +36,32 @@ execute the hook logic inside of the Gitaly server process. It uses the injected information to connect to Gitaly and execute the respective RPC call. The execution path is: -1. Git locates the hook using `core.hooksPath`. If found, this is a symlink - which points to the `gitaly-hooks` executable. +1. Gitaly symlinks `pre-receive`, `update`, `post-receive`, and + `reference-transaction` hooks to the `gitaly-hooks` binary from a + subdirectory of Gitaly's runtime directory. +1. Git locates the hook using `core.hooksPath`. 1. `gitaly-hooks` connects to Gitaly and executes the corresponding RPC call in Gitaly, passing along any hook-specific information to the RPC. 1. Gitaly performs the hook-specific logic in the RPC handler. +## `gitaly-hooks` binary + +`gitaly-hooks` is a binary that is the single point of entry for git hooks +through gitaly. + +### Subcommands + +`gitaly-hooks` has the following subcommands: + +| subcommand | purpose | arguments | stdin | +|----------------|----------|-----------|--------| +| `check` | checks if the hooks can reach the gitlab server | none | none | +| `pre-receive` | used as the git pre-receive hook none | `` SP `` SP `` LF | +| `update` | used as the git update hook | `` `` `` | none +| `post-receive` | used as the git post-receive hook | none | `` SP `` SP `` LF | +| `reference-transaction` | used as the git reference-transactionhook | `prepared|committed|aborted` | `` SP `` SP `` LF | +| `git` | used as the git pack-objects hook | `pack-objects` `[--stdout]` `[--shallow-file]` | `` | + ## Hook-specific logic The logic implemented in Gitaly's hook RPC handlers depends on which hook is -- cgit v1.2.3