feat: support user-defined custom commands in PR welcome message

AGENTS.md

@@ -195,6 +195,20 @@ Post-resolution verification: `_verify_cherry_pick_scope()` compares `git diff -
 
 Required env vars for pi-sidecar: `ACPX_AGENTS=cursor`, `VERTEX_CLAUDE_1M=true`, `GOOGLE_APPLICATION_CREDENTIALS`.
 
+### Custom Commands
+
+User-defined commands rendered in the PR welcome message. Documentation-only — the server displays them but does NOT process them. External bots/tools handle them independently.
+
+**Schema:** `webhook_server/config/schema.yaml` (`custom-commands` at global level, `$defs.custom-command-item` for DRY)
+
+**Config:** Three resolution layers (first match wins, no list merge): (1) repo-local `.github-webhook-server.yaml`, (2) `repositories.<repo>.custom-commands` in `config.yaml`, (3) root-level `custom-commands` in `config.yaml`. Per-repo layers can use an empty list (`custom-commands: []`) to disable global defaults; the root-level schema requires `minItems: 1` and `maxItems: 50`.
+
+**Validation:** `GithubWebhook._validate_custom_commands()` in `webhook_server/libs/github_api.py` — validates at load time (entries must be dicts with non-empty `name` (max 100 chars) matching `^[a-zA-Z0-9_-]+$` and non-empty `description` (max 500 chars); duplicate names are rejected, keeping only the first occurrence). Invalid and duplicate entries are logged and skipped.
+
+**Handler:** `PullRequestHandler._prepare_custom_commands_welcome_section` in `webhook_server/libs/handlers/pull_request_handler.py` — renders a "Custom Commands" section with each command as `` * `/{name}` - description ``. Descriptions are markdown-escaped via `_escape_markdown()`.
+
+**Config loading:** `self.custom_commands` loaded in `GithubWebhook._repo_data_from_config()` via `self.config.get_value("custom-commands", ...)` with `extra_dict=repository_config` for per-repo override support.
+
 ### Sidecar Architecture
 
 `sidecar-helper/` — Node.js pi-sidecar bridge for AI provider integration. Minimal TypeScript wrapper importing `@myk-org/pi-sidecar`.

README.md

@@ -17,6 +17,7 @@ A [FastAPI](https://fastapi.tiangolo.com)-based webhook server for automating Gi
 - **OWNERS-Based Permissions** — reviewer and approver assignment from OWNERS files with per-directory granularity
 - **Container and PyPI Publishing** — automated container builds, tag-based releases, and PyPI publishing
 - **Issue Comment Commands** — `/retest`, `/approve`, `/cherry-pick`, `/build-and-push-container`, and more
+- **Custom Commands** — user-defined documentation-only commands rendered in the PR welcome message
 - **AI Features** — conventional commit title validation and suggestions via Claude, Gemini, or Cursor
 - **Repository Bootstrap** — automatic label creation, branch protection, and webhook configuration on startup
 - **Log Viewer** — real-time log streaming, webhook flow visualization, and structured log analysis

examples/config.yaml

@@ -314,3 +314,12 @@ repositories:
     #     - ".github/workflows/"
     #     - ".github/actions/"
     #   committer-identity-check: true
+
+    # Custom commands to display in PR welcome message (documentation-only)
+    # These commands are shown in the welcome comment but not processed by the server.
+    # External bots or tools handle them independently.
+    # custom-commands:
+    #   - name: deploy-staging
+    #     description: Deploy this PR to the staging environment
+    #   - name: run-e2e
+    #     description: Trigger end-to-end test suite against this PR

pyproject.toml

@@ -109,4 +109,4 @@ dev = [
   "types-pyyaml>=6.0.12.20250516",
   "types-requests>=2.32.4.20250611",
 ]
-tests = ["psutil>=7.0.0", "pytest-asyncio>=0.26.0", "pytest-xdist>=3.7.0"]
+tests = ["jsonschema>=4.0.0", "psutil>=7.0.0", "pytest-asyncio>=0.26.0", "pytest-xdist>=3.7.0"]

webhook_server/config/schema.yaml

@@ -68,6 +68,24 @@ $defs:
       - ai-provider
       - ai-model
     additionalProperties: false
+  custom-command-item:
+    type: object
+    properties:
+      name:
+        type: string
+        pattern: "^[a-zA-Z0-9_-]+$"
+        minLength: 1
+        maxLength: 100
+        description: Command name (without the leading slash)
+      description:
+        type: string
+        minLength: 1
+        maxLength: 500
+        description: Human-readable description of what the command does
+    required:
+      - name
+      - description
+    additionalProperties: false
   security-checks:
     type: object
     description: |
@@ -253,6 +271,16 @@ properties:
     $ref: '#/$defs/ai-features'
   security-checks:
     $ref: '#/$defs/security-checks'
+  custom-commands:
+    type: array
+    minItems: 1
+    maxItems: 50
+    description: |
+      Custom commands to display in the PR welcome message (global default).
+      These are documentation-only - the server renders them in the welcome
+      message but does NOT process them. External bots or tools handle them.
+    items:
+      $ref: '#/$defs/custom-command-item'
   labels:
     type: object
     description: Configure which labels are enabled and their colors
@@ -716,3 +744,20 @@ properties:
               - name
               - command
             additionalProperties: false
+        custom-commands:
+          type: array
+          maxItems: 50
+          description: |
+            Custom commands to display in the PR welcome message (per-repo override).
+            These are documentation-only - the server renders them in the welcome
+            message but does NOT process them. External bots or tools handle them.
+            An empty list is allowed to explicitly disable global custom-commands
+            for this repository.
+
+            Examples:
+              - name: deploy-staging
+                description: Deploy this PR to the staging environment
+              - name: run-e2e
+                description: Trigger end-to-end test suite against this PR
+          items:
+            $ref: '#/$defs/custom-command-item'

webhook_server/libs/github_api.py

@@ -32,6 +32,7 @@
 from webhook_server.utils.constants import (
     BUILD_CONTAINER_STR,
     BUILTIN_CHECK_NAMES,
+    BUILTIN_COMMAND_NAMES,
     CAN_BE_MERGED_STR,
     CONFIGURABLE_LABEL_CATEGORIES,
     CONVENTIONAL_TITLE_STR,
@@ -941,6 +942,11 @@ def _repo_data_from_config(self, repository_config: dict[str, Any]) -> None:
         )
         self.custom_check_runs: list[dict[str, Any]] = self._validate_custom_check_runs(raw_custom_checks)
 
+        raw_custom_commands = self.config.get_value(
+            value="custom-commands", return_on_none=[], extra_dict=repository_config
+        )
+        self.custom_commands: list[dict[str, str]] = self._validate_custom_commands(raw_custom_commands)
+
         _auto_users = self.config.get_value(
             value="auto-verified-and-merged-users", return_on_none=[], extra_dict=repository_config
         )
@@ -1596,6 +1602,100 @@ def _validate_custom_check_runs(self, raw_checks: object) -> list[dict[str, Any]
 
         return validated_checks
 
+    def _validate_custom_commands(self, raw_commands: object) -> list[dict[str, str]]:
+        """Validate custom commands configuration at load time.
+
+        Validates each custom command entry and returns only valid ones:
+        - Checks that entry is a dict with 'name' and 'description' string fields
+        - Verifies name matches the safe pattern [a-zA-Z0-9_-]+
+        - Logs warnings for invalid entries and skips them
+
+        Args:
+            raw_commands: Custom command configurations from config (should be a list)
+
+        Returns:
+            List of validated custom command configurations
+        """
+        if not isinstance(raw_commands, list):
+            prefix = getattr(self, "log_prefix", "")
+            log_msg_prefix = f"{prefix} " if prefix else ""
+            self.logger.warning(
+                f"{log_msg_prefix}custom-commands config is not a list (got {type(raw_commands).__name__}), skipping"
+            )
+            return []
+
+        # Use getattr since log_prefix may not be set during early __init__ calls
+        prefix = getattr(self, "log_prefix", "")
+        log_msg_prefix = f"{prefix} " if prefix else ""
+        safe_name_pattern = re.compile(r"^[a-zA-Z0-9_-]+$")
+        seen_names: set[str] = set()
+        validated: list[dict[str, str]] = []
+
+        for cmd in raw_commands:
+            if not isinstance(cmd, dict):
+                self.logger.warning(f"{log_msg_prefix}Custom command entry is not a mapping, skipping")
+                continue
+
+            name = cmd.get("name")
+            description = cmd.get("description")
+            if not isinstance(name, str) or not name:
+                self.logger.warning(f"{log_msg_prefix}Custom command missing or invalid 'name', skipping")
+                continue
+
+            if len(name) > 100:
+                self.logger.warning(
+                    f"{log_msg_prefix}Custom command name {name[:20]!r}... exceeds 100 characters, skipping"
+                )
+                continue
+
+            if not safe_name_pattern.fullmatch(name):
+                self.logger.warning(
+                    f"{log_msg_prefix}Custom command name {name!r} does not match safe pattern, skipping"
+                )
+                continue
+
+            if name.lower() in BUILTIN_COMMAND_NAMES:
+                self.logger.warning(
+                    f"{log_msg_prefix}Custom command name {name!r} collides with built-in command, skipping"
+                )
+                continue
+
+            if not isinstance(description, str) or not description:
+                self.logger.warning(
+                    f"{log_msg_prefix}Custom command '{name}' missing or invalid 'description', skipping"
+                )
+                continue
+
+            if len(description) > 500:
+                self.logger.warning(
+                    f"{log_msg_prefix}Custom command '{name}' description exceeds 500 characters, skipping"
+                )
+                continue
+
+            if name.lower() in seen_names:
+                self.logger.warning(
+                    f"{log_msg_prefix}Duplicate custom command name {name!r} (case-insensitive), skipping"
+                )
+                continue
+            seen_names.add(name.lower())
+
+            validated.append({"name": name, "description": description})
+
+        if validated:
+            self.logger.info(
+                f"{log_msg_prefix}Loaded {len(validated)} custom command(s): {[c['name'] for c in validated]}"
+            )
+        if raw_commands and not validated:
+            self.logger.warning(
+                f"{log_msg_prefix}No valid custom commands loaded — all {len(raw_commands)} entries were invalid"
+            )
+        elif len(validated) < len(raw_commands):
+            self.logger.warning(
+                f"{log_msg_prefix}Skipped {len(raw_commands) - len(validated)} invalid custom command(s)"
+            )
+
+        return validated
+
     def __del__(self) -> None:
         """Remove the shared clone directory when the webhook object is destroyed.
 

webhook_server/libs/handlers/pull_request_handler.py

@@ -497,6 +497,7 @@ def _prepare_welcome_comment(self) -> str:
 {self._prepare_retest_welcome_comment}
 {self._prepare_container_operations_welcome_section}\
 {self._prepare_cherry_pick_section}\
+{self._prepare_custom_commands_welcome_section}\
 
 #### Label Management
 * `/<label-name>` - Add a label to the PR
@@ -842,6 +843,44 @@ def _prepare_cherry_pick_section(self) -> str:
 """
         return "\n#### Branch Management\n* `/rebase` - Rebase this PR branch onto its base branch\n"
 
+    @staticmethod
+    def _escape_markdown(text: str) -> str:
+        """Escape markdown special characters in text.
+
+        Prevents markdown injection when inserting user-provided text
+        into PR comments. Escapes backslashes first to avoid interaction
+        with subsequently escaped characters, then escapes characters that
+        could create links, images, inline code, bold, underline,
+        strikethrough, or HTML tags, and neutralizes @mentions.
+        """
+        text = text.replace("\\", "\\\\")
+        for char in ("[", "]", "(", ")", "!", "`", "*", "_", "~", "<", ">"):
+            text = text.replace(char, f"\\{char}")
+        # Neutralize @mentions to prevent unintended user/team pings
+        text = text.replace("@", "@\u200b")
+        return text
+
+    @property
+    def _prepare_custom_commands_welcome_section(self) -> str:
+        """Prepare the Custom Commands section for the welcome comment.
+
+        Renders user-defined custom commands from configuration.
+        These are documentation-only - the server does not process them.
+        Commands are validated at load time by GithubWebhook._validate_custom_commands().
+        """
+        custom_commands: list[dict[str, str]] = self.github_webhook.custom_commands
+        if not custom_commands:
+            return ""
+
+        lines: list[str] = ["\n#### Custom Commands"]
+        for cmd in custom_commands:
+            name = cmd["name"]
+            description = cmd["description"]
+            sanitized = self._escape_markdown(description.replace("\n", " ").replace("\r", " "))
+            lines.append(f"* `/{name}` - {sanitized}")
+
+        return "\n".join(lines) + "\n"
+
     async def label_all_opened_pull_requests_merge_state_after_merged(self) -> None:
         """
         Labels pull requests based on their mergeable state.

webhook_server/tests/test_ai_cli.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
-from webhook_server.libs.ai_cli import get_ai_config
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from webhook_server.libs.ai_cli import AIResult, call_ai, get_ai_config
 
 
 class TestGetAiConfig:
@@ -23,3 +27,60 @@ def test_get_ai_config_partial_missing_model(self) -> None:
 
     def test_get_ai_config_partial_missing_provider(self) -> None:
         assert get_ai_config({"ai-model": "sonnet"}) is None
+
+
+class TestCallAi:
+    """Test suite for call_ai function."""
+
+    @pytest.mark.asyncio
+    async def test_call_ai_sidecar_unavailable(self) -> None:
+        """Test call_ai returns error when sidecar is unavailable."""
+        with patch(
+            "webhook_server.libs.ai_cli.check_sidecar_available",
+            new_callable=AsyncMock,
+            return_value=(False, "connection refused"),
+        ):
+            result = await call_ai(
+                prompt="test",
+                ai_provider="claude",
+                ai_model="sonnet",
+                cwd="/tmp",
+            )
+            assert result.success is False
+            assert "Pi-sidecar unavailable" in result.error
+            assert "connection refused" in result.error
+
+    @pytest.mark.asyncio
+    async def test_call_ai_sidecar_available(self) -> None:
+        """Test call_ai delegates to call_ai_once when sidecar is available."""
+        expected = AIResult(success=True, text="hello", error="")
+        with patch(
+            "webhook_server.libs.ai_cli.check_sidecar_available",
+            new_callable=AsyncMock,
+            return_value=(True, "ok"),
+        ):
+            with patch(
+                "webhook_server.libs.ai_cli.call_ai_once",
+                new_callable=AsyncMock,
+                return_value=expected,
+            ) as mock_call:
+                result = await call_ai(
+                    prompt="test",
+                    ai_provider="claude",
+                    ai_model="sonnet",
+                    cwd="/tmp",
+                    timeout_minutes=5,
+                    system_prompt="be helpful",
+                )
+                assert result.success is True
+                assert result.text == "hello"
+                mock_call.assert_awaited_once_with(
+                    prompt="test",
+                    ai_provider="claude",
+                    ai_model="sonnet",
+                    cwd="/tmp",
+                    ai_call_timeout=5,
+                    system_prompt="be helpful",
+                    tools=None,
+                    custom_tools=None,
+                )