Implement server-side git hooks (pre-receive, update, post-receive)

Fixes #212

Author: jelmer

NEWS

@@ -5,6 +5,12 @@
 
  * Add basic support for subtrees. (Jelmer Vernooij)
 
+ * Implement server-side Git hooks (pre-receive, update, post-receive) in
+   ``ReceivePackHandler``. Pre-receive hooks can abort entire pushes, update
+   hooks can decline individual ref updates, and post-receive hooks run after
+   successful pushes. Hook output is sent to clients via sideband channels.
+   (Jelmer Vernooij, #212)
+
  * Report progress during pack file downloads. Dulwich now displays real-time
    transfer progress (bytes received, transfer speed) when cloning or fetching
    repositories, matching Git's behavior. (Jelmer Vernooij, #1121)

dulwich/hooks.py

@@ -27,7 +27,9 @@
     "PostCommitShellHook",
     "PostReceiveShellHook",
     "PreCommitShellHook",
+    "PreReceiveShellHook",
     "ShellHook",
+    "UpdateShellHook",
 ]
 
 import os
@@ -244,3 +246,121 @@ def execute(
             return out_data
         except OSError as err:
             raise HookError(repr(err)) from err
+
+
+class PreReceiveShellHook(ShellHook):
+    """pre-receive shell hook."""
+
+    def __init__(self, controldir: str) -> None:
+        """Initialize pre-receive hook.
+
+        Args:
+            controldir: Path to the git control directory (.git)
+        """
+        self.controldir = controldir
+        filepath = os.path.join(controldir, "hooks", "pre-receive")
+        ShellHook.__init__(self, "pre-receive", path=filepath, numparam=0)
+
+    def execute(
+        self, client_refs: Sequence[tuple[bytes, bytes, bytes]]
+    ) -> tuple[bytes, bytes]:
+        """Execute the pre-receive hook.
+
+        Args:
+            client_refs: List of tuples containing (old_sha, new_sha, ref_name)
+                        for each reference to be updated
+
+        Returns:
+            Tuple of (stdout, stderr) from hook execution
+
+        Raises:
+            HookError: If hook execution fails (exits with non-zero status)
+        """
+        # do nothing if the script doesn't exist
+        if not os.path.exists(self.filepath):
+            return (b"", b"")
+
+        try:
+            env = os.environ.copy()
+            env["GIT_DIR"] = self.controldir
+
+            p = subprocess.Popen(
+                self.filepath,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+            )
+
+            # client_refs is a list of (oldsha, newsha, ref)
+            in_data = b"\n".join([b" ".join(ref) for ref in client_refs])
+
+            out_data, err_data = p.communicate(in_data)
+
+            if p.returncode != 0:
+                raise HookError(
+                    f"pre-receive hook exited with status {p.returncode}: {err_data.decode('utf-8', 'backslashreplace')}"
+                )
+            return (out_data, err_data)
+        except OSError as err:
+            raise HookError(repr(err)) from err
+
+
+class UpdateShellHook(ShellHook):
+    """update shell hook."""
+
+    def __init__(self, controldir: str) -> None:
+        """Initialize update hook.
+
+        Args:
+            controldir: Path to the git control directory (.git)
+        """
+        self.controldir = controldir
+        filepath = os.path.join(controldir, "hooks", "update")
+        ShellHook.__init__(self, "update", path=filepath, numparam=3)
+
+    def execute(
+        self, ref_name: bytes, old_sha: bytes, new_sha: bytes
+    ) -> tuple[bytes, bytes]:
+        """Execute the update hook for a single ref.
+
+        Args:
+            ref_name: Name of the reference being updated
+            old_sha: Old SHA of the reference
+            new_sha: New SHA of the reference
+
+        Returns:
+            Tuple of (stdout, stderr) from hook execution
+
+        Raises:
+            HookError: If hook execution fails (exits with non-zero status)
+        """
+        # do nothing if the script doesn't exist
+        if not os.path.exists(self.filepath):
+            return (b"", b"")
+
+        try:
+            env = os.environ.copy()
+            env["GIT_DIR"] = self.controldir
+
+            p = subprocess.Popen(
+                [
+                    self.filepath,
+                    ref_name.decode("utf-8", "backslashreplace"),
+                    old_sha.decode("utf-8", "backslashreplace"),
+                    new_sha.decode("utf-8", "backslashreplace"),
+                ],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+            )
+
+            out_data, err_data = p.communicate()
+
+            if p.returncode != 0:
+                raise HookError(
+                    f"update hook exited with status {p.returncode}: {err_data.decode('utf-8', 'backslashreplace')}"
+                )
+            return (out_data, err_data)
+        except OSError as err:
+            raise HookError(repr(err)) from err

dulwich/repo.py

@@ -107,6 +107,8 @@
     PostCommitShellHook,
     PostReceiveShellHook,
     PreCommitShellHook,
+    PreReceiveShellHook,
+    UpdateShellHook,
 )
 from .object_store import (
     DiskObjectStore,
@@ -1530,6 +1532,8 @@ def __init__(
         self.hooks["pre-commit"] = PreCommitShellHook(self.path, self.controldir())
         self.hooks["commit-msg"] = CommitMsgShellHook(self.controldir())
         self.hooks["post-commit"] = PostCommitShellHook(self.controldir())
+        self.hooks["pre-receive"] = PreReceiveShellHook(self.controldir())
+        self.hooks["update"] = UpdateShellHook(self.controldir())
         self.hooks["post-receive"] = PostReceiveShellHook(self.controldir())
 
         # Initialize filter context as None, will be created lazily

dulwich/server.py

@@ -1461,6 +1461,15 @@ def _apply_pack(
 
         for oldsha, sha, ref in refs:
             ref_status = b"ok"
+
+            # Run update hook for this ref
+            hook_error = self._on_update(ref, oldsha, sha)
+            if hook_error:
+                # Update hook declined this ref
+                ref_status = hook_error
+                yield (ref, ref_status)
+                continue
+
             try:
                 if sha == zero_sha:
                     if CAPABILITY_DELETE_REFS not in self.capabilities():
@@ -1512,6 +1521,68 @@ def flush() -> None:
         write(None)  # type: ignore
         flush()
 
+    def _on_pre_receive(
+        self, client_refs: list[tuple[ObjectID, ObjectID, Ref]]
+    ) -> None:
+        """Run pre-receive hook.
+
+        Args:
+            client_refs: List of (old_sha, new_sha, ref_name) tuples
+
+        Raises:
+            HookError: If hook fails, preventing the push
+        """
+        hook = self.repo.hooks.get("pre-receive", None)  # type: ignore[attr-defined]
+        if not hook:
+            return
+        try:
+            stdout, stderr = hook.execute(client_refs)
+            # Only send output via sideband if capabilities are set
+            if self._client_capabilities is not None:
+                if stdout and self.has_capability(CAPABILITY_SIDE_BAND_64K):
+                    self.proto.write_sideband(SIDE_BAND_CHANNEL_PROGRESS, stdout)
+                if stderr and self.has_capability(CAPABILITY_SIDE_BAND_64K):
+                    self.proto.write_sideband(SIDE_BAND_CHANNEL_PROGRESS, stderr)
+        except HookError as err:
+            # Send error to client via sideband if available
+            if self._client_capabilities is not None and self.has_capability(
+                CAPABILITY_SIDE_BAND_64K
+            ):
+                self.proto.write_sideband(
+                    SIDE_BAND_CHANNEL_FATAL, str(err).encode("utf-8")
+                )
+            # Re-raise to abort the push
+            raise
+
+    def _on_update(
+        self, ref_name: Ref, old_sha: ObjectID, new_sha: ObjectID
+    ) -> bytes | None:
+        """Run update hook for a single ref.
+
+        Args:
+            ref_name: Name of the reference
+            old_sha: Old SHA of the reference
+            new_sha: New SHA of the reference
+
+        Returns:
+            Error message if hook fails, None otherwise
+        """
+        hook = self.repo.hooks.get("update", None)  # type: ignore[attr-defined]
+        if not hook:
+            return None
+        try:
+            stdout, stderr = hook.execute(ref_name, old_sha, new_sha)
+            # Only send output via sideband if capabilities are set
+            if self._client_capabilities is not None:
+                if stdout and self.has_capability(CAPABILITY_SIDE_BAND_64K):
+                    self.proto.write_sideband(SIDE_BAND_CHANNEL_PROGRESS, stdout)
+                if stderr and self.has_capability(CAPABILITY_SIDE_BAND_64K):
+                    self.proto.write_sideband(SIDE_BAND_CHANNEL_PROGRESS, stderr)
+            return None
+        except HookError as err:
+            # Return error message to mark this ref as failed
+            return str(err).encode("utf-8")
+
     def _on_post_receive(self, client_refs: dict[bytes, tuple[bytes, bytes]]) -> None:
         """Run post-receive hook.
 
@@ -1569,6 +1640,22 @@ def handle(self) -> None:
             client_refs.append((ObjectID(oldsha), ObjectID(newsha), Ref(ref_name)))
             ref_line = self.proto.read_pkt_line()
 
+        # Run pre-receive hook before processing the pack
+        # If it fails, we abort the entire push
+        try:
+            self._on_pre_receive(client_refs)
+        except HookError:
+            # Hook failed, report error to client and abort
+            # We still need to consume the pack data to avoid protocol errors
+            if self.has_capability(CAPABILITY_REPORT_STATUS):
+                # Send unpack error status
+                status = [(b"unpack", b"pre-receive hook declined")]
+                # Add 'ng' (not good) status for all refs
+                for _, _, ref_name in client_refs:
+                    status.append((ref_name, b"pre-receive hook declined"))
+                self._report_status(status)
+            return
+
         # backend can now deal with this refs and read a pack using self.read
         status = list(self._apply_pack(client_refs))
 

tests/test_server.py

@@ -30,6 +30,7 @@
 from dulwich.errors import (
     GitProtocolError,
     HangupException,
+    HookError,
     NotGitRepository,
     UnexpectedCommandError,
 )
@@ -387,6 +388,110 @@ def test_apply_pack_del_ref(self) -> None:
         self.assertEqual(status[1][0], b"refs/heads/fake-branch")
         self.assertEqual(status[1][1], b"ok")
 
+    def test_pre_receive_hook_success(self) -> None:
+        """Test that pre-receive hook is called and can succeed."""
+
+        def mock_hook_execute(client_refs):
+            # Verify the hook receives the expected refs
+            self.assertEqual(len(client_refs), 1)
+            self.assertEqual(client_refs[0][0], ONE)
+            self.assertEqual(client_refs[0][1], TWO)
+            self.assertEqual(client_refs[0][2], b"refs/heads/master")
+            return (b"", b"")
+
+        # Create a mock hook
+        from unittest.mock import Mock
+
+        mock_hook = Mock()
+        mock_hook.execute = mock_hook_execute
+        self._repo.hooks["pre-receive"] = mock_hook
+
+        # Test that the hook is called
+        client_refs = [(ONE, TWO, b"refs/heads/master")]
+        self._handler._on_pre_receive(client_refs)
+
+    def test_pre_receive_hook_failure(self) -> None:
+        """Test that pre-receive hook can abort a push."""
+
+        def mock_hook_execute(client_refs):
+            raise HookError("pre-receive hook declined")
+
+        # Create a mock hook
+        from unittest.mock import Mock
+
+        mock_hook = Mock()
+        mock_hook.execute = mock_hook_execute
+        self._repo.hooks["pre-receive"] = mock_hook
+
+        # Test that the hook failure raises HookError
+        client_refs = [(ONE, TWO, b"refs/heads/master")]
+        self.assertRaises(HookError, self._handler._on_pre_receive, client_refs)
+
+    def test_update_hook_success(self) -> None:
+        """Test that update hook is called and can succeed."""
+
+        def mock_hook_execute(ref_name, old_sha, new_sha):
+            # Verify the hook receives the expected arguments
+            self.assertEqual(ref_name, b"refs/heads/master")
+            self.assertEqual(old_sha, ONE)
+            self.assertEqual(new_sha, TWO)
+            return (b"", b"")
+
+        # Create a mock hook
+        from unittest.mock import Mock
+
+        mock_hook = Mock()
+        mock_hook.execute = mock_hook_execute
+        self._repo.hooks["update"] = mock_hook
+
+        # Test that the hook is called
+        result = self._handler._on_update(b"refs/heads/master", ONE, TWO)
+        self.assertIsNone(result)
+
+    def test_update_hook_failure(self) -> None:
+        """Test that update hook can decline a ref update."""
+
+        def mock_hook_execute(ref_name, old_sha, new_sha):
+            raise HookError("update hook declined")
+
+        # Create a mock hook
+        from unittest.mock import Mock
+
+        mock_hook = Mock()
+        mock_hook.execute = mock_hook_execute
+        self._repo.hooks["update"] = mock_hook
+
+        # Test that the hook failure returns an error message
+        result = self._handler._on_update(b"refs/heads/master", ONE, TWO)
+        self.assertIsNotNone(result)
+        self.assertIn(b"update hook declined", result)
+
+    def test_update_hook_declines_ref(self) -> None:
+        """Test that update hook can decline a ref during pack application."""
+        refs = {b"refs/heads/master": ONE}
+        self._repo.refs._update(refs)
+
+        # Create a hook that declines the ref
+        def mock_hook_execute(ref_name, old_sha, new_sha):
+            raise HookError("update hook declined this ref")
+
+        # Create a mock hook
+        from unittest.mock import Mock
+
+        mock_hook = Mock()
+        mock_hook.execute = mock_hook_execute
+        self._repo.hooks["update"] = mock_hook
+
+        # Test the ref update part without reading pack data
+        self._handler.set_client_capabilities([b"delete-refs"])
+
+        # The update hook should decline the ref
+        ref_status = self._handler._on_update(b"refs/heads/master", ONE, ZERO_SHA)
+
+        # Verify hook declined the ref
+        self.assertIsNotNone(ref_status)
+        self.assertIn(b"update hook declined", ref_status)
+
 
 class ProtocolGraphWalkerEmptyTestCase(TestCase):
     def setUp(self) -> None: