docs: add webhook operations guardrails

Author: tae2089

guide/docker.md

@@ -30,6 +30,33 @@ balancer, keep health and status endpoints internal. `/health`, `/ready`, and
 to the public internet. See the [Operations Guide](operations.md#http-exposure)
 for endpoint exposure guidance.
 
+Example reverse-proxy policy:
+
+| Path | Public Internet | Internal Network |
+|------|-----------------|------------------|
+| `/mcp` | Allowed only with bearer auth and network policy | Allowed |
+| `/webhook` | Allowed only with HMAC secret and repo allowlist | Allowed |
+| `/health` | Blocked | Allowed |
+| `/ready` | Blocked | Allowed |
+| `/status` | Blocked | Allowed |
+
+For webhook service mode, use a canonical clone base URL and keep one
+organization/owner per CCG instance unless the repo names are guaranteed unique:
+
+```bash
+docker run -d -p 8080:8080 \
+  -e CCG_HTTP_BEARER_TOKEN="$CCG_HTTP_BEARER_TOKEN" \
+  -e CCG_DB_DRIVER=postgres \
+  -e CCG_DB_DSN="$CCG_DB_DSN" \
+  -e CCG_REPO_ROOT=/data/repos \
+  -v ccg-repos:/data/repos \
+  --entrypoint ccg ccg \
+  serve --transport streamable-http --http-addr :8080 \
+    --allow-repo "acme/*" \
+    --webhook-secret "$WEBHOOK_SECRET" \
+    --repo-clone-base-url https://github.com
+```
+
 For the mounted default local SQLite database, use an explicit migration command
 when upgrading CCG against an existing schema:
 

guide/ko/docker.md

@@ -27,6 +27,32 @@ docker run -d -p 8080:8080 \
 
 이 컨테이너가 Ingress, 리버스 프록시 또는 로드 밸런서를 통해 노출되는 경우, 헬스 체크 및 상태 엔드포인트는 내부용으로 유지하십시오. `/health`, `/ready`, `/status`는 신뢰할 수 있는 운영 체크를 위한 것이며 공용 인터넷에 노출되어서는 안 됩니다. 엔드포인트 노출 가이드는 [운영 가이드](operations.md#http-exposure)를 참조하십시오.
 
+리버스 프록시 정책 예시:
+
+| 경로 | 공용 인터넷 | 내부 네트워크 |
+|------|-------------|---------------|
+| `/mcp` | Bearer 인증 및 네트워크 정책이 있을 때만 허용 | 허용 |
+| `/webhook` | HMAC secret 및 repo allowlist가 있을 때만 허용 | 허용 |
+| `/health` | 차단 | 허용 |
+| `/ready` | 차단 | 허용 |
+| `/status` | 차단 | 허용 |
+
+웹훅 서비스 모드에서는 canonical clone base URL을 사용하고, repo 이름 중복이 없다는 보장이 없다면 CCG 인스턴스 하나에는 하나의 조직/owner만 연결하십시오.
+
+```bash
+docker run -d -p 8080:8080 \
+  -e CCG_HTTP_BEARER_TOKEN="$CCG_HTTP_BEARER_TOKEN" \
+  -e CCG_DB_DRIVER=postgres \
+  -e CCG_DB_DSN="$CCG_DB_DSN" \
+  -e CCG_REPO_ROOT=/data/repos \
+  -v ccg-repos:/data/repos \
+  --entrypoint ccg ccg \
+  serve --transport streamable-http --http-addr :8080 \
+    --allow-repo "acme/*" \
+    --webhook-secret "$WEBHOOK_SECRET" \
+    --repo-clone-base-url https://github.com
+```
+
 마운트된 기본 로컬 SQLite 데이터베이스의 경우, 기존 스키마에 대해 CCG를 업그레이드할 때는 명시적인 마이그레이션 명령어를 사용하십시오:
 
 ```bash

guide/ko/operations.md

@@ -168,6 +168,15 @@ CCG가 Ingress, 리버스 프록시 또는 로드 밸런서 뒤에 있는 경우
 - 지속성 있는 로컬 스토리지를 위한 `--repo-root`
 - 팀용 또는 상시 가동 배포를 위한 `--db-driver postgres`
 
+웹훅 네임스페이스 추출은 마지막 저장소 이름을 사용합니다. 예를 들어 `acme/api`는 `api` 네임스페이스에 저장되고 `$REPO_ROOT/api`에 checkout됩니다. 이 전략은 단일 owner 웹훅 배포를 위한 것입니다. 허용 목록이 여러 owner를 포함하면 서버는 경고를 남깁니다. `acme/api`와 `external/api`가 같은 네임스페이스 및 checkout 경로에서 충돌할 수 있기 때문입니다.
+
+권장 정책:
+
+- 웹훅 CCG 인스턴스 하나에는 하나의 조직/owner를 사용하십시오.
+- 인스턴스 안에서 마지막 저장소 이름이 중복되지 않게 유지하십시오.
+- 서로 다른 조직에 같은 repo 이름이 있을 수 있으면 CCG 인스턴스를 분리하십시오.
+- `*/*`는 일반 운영 allowlist가 아니라 개발 또는 격리된 환경에서만 신중히 사용하십시오.
+
 SQLite 웹훅 배포는 `--webhook-workers` 또는 `CCG_WEBHOOK_WORKERS`가 명시적으로 설정되지 않으면 기본적으로 하나의 워커를 사용합니다. 이는 동일한 SQLite 데이터베이스에 대해 여러 동시 쓰기 작업이 발생하는 것을 방지하기 위함입니다. PostgreSQL의 경우, 저장소 업데이트 시간, 데이터베이스 용량 및 허용 가능한 큐 대기 시간에 따라 워커 수를 조정해야 합니다.
 
 큐 메모리를 제한하려면 `--webhook-max-tracked-repos`를 사용하십시오. 큐가 가득 차면 새로운 저장소 요청은 `429 Too Many Requests`로 거부됩니다. 이러한 현상이 반복되면 규모 확장이나 범위 조정 문제로 취급해야 합니다.
@@ -210,9 +219,20 @@ SQLite 웹훅 배포는 `--webhook-workers` 또는 `CCG_WEBHOOK_WORKERS`가 명
 
 SIGINT/SIGTERM 수신 시:
 
-1. HTTP는 5초의 종료 윈도우와 함께 새로운 요청 수락을 중단합니다.
+1. HTTP는 `--webhook-shutdown-timeout`(기본 30초)의 종료 윈도우와 함께 새로운 요청 수락을 중단합니다.
 2. 동기화 컨텍스트가 취소되고 진행 중인 복제/빌드 작업이 `context.Done()`을 감지합니다.
-3. SyncQueue 워커는 드레인(drain)을 위해 최대 30초의 시간을 갖습니다.
+3. SyncQueue 워커는 드레인(drain)을 위해 최대 `--webhook-shutdown-timeout`의 시간을 갖습니다.
+
+큐 종료가 시작된 뒤 들어온 웹훅 delivery는 `503 Service Unavailable`을 반환하므로 GitHub/Gitea가 이벤트를 성공 처리하지 않고 재시도할 수 있습니다. 종료 직전에 수락된 요청은 프로세스 종료로 취소될 수 있으므로, 새 push 또는 수동 네임스페이스 업데이트로 복구하십시오.
+
+수동 복구:
+
+```bash
+ccg update /data/repos/api --namespace api
+ccg status --namespace api --errors
+```
+
+검색, 커뮤니티, 저장된 flow가 여전히 오래된 것처럼 보이면 namespace `api`에 대해 필요한 postprocess 플래그와 함께 MCP `run_postprocess` 도구를 호출하십시오.
 
 Streamable HTTP 서버는 MCP 스트림이 장시간 유지될 수 있으므로 고정된 `WriteTimeout`을 사용하지 않습니다. 서비스가 인터넷에 노출된 경우 리버스 프록시에서 유휴 연결 제한 및 요청 버퍼링 정책을 설정하십시오.
 

guide/ko/webhook.md

@@ -76,6 +76,23 @@ ccg serve --transport streamable-http \
 2. 일치하는 규칙이 없으면 거부됩니다.
 3. 웹훅 페이로드의 `ref` 필드에서 `refs/heads/` 접두사는 자동으로 제거됩니다.
 
+### 네임스페이스 전략과 단일 조직 운영
+
+웹훅 동기화는 `org/repo` 중 마지막 저장소 이름을 그래프 네임스페이스와 checkout 디렉터리로 사용합니다. 예를 들어 `acme/api`는 `api` 네임스페이스와 `/data/repos/api` checkout으로 매핑됩니다.
+
+이 방식은 단일 조직 배포에서 짧고 예측 가능한 이름을 유지하기 위한 전략이며, 권장 운영 모델입니다. 허용 목록이 `acme/*`와 `external/shared`처럼 여러 owner를 포함하거나 `*/*`를 사용하면, 같은 마지막 저장소 이름이 충돌할 수 있으므로 CCG는 시작 시 경고 로그를 남깁니다.
+
+| 저장소 | 파생 네임스페이스 |
+|------|-------------------|
+| `acme/api` | `api` |
+| `external/api` | `api` |
+
+운영 정책:
+
+- 웹훅 CCG 인스턴스 하나에는 하나의 owner/조직을 사용하는 것을 권장합니다.
+- 같은 인스턴스 안에 마지막 저장소 이름이 같은 저장소를 허용하지 마십시오.
+- 여러 owner의 동기화가 필요하면 별도 CCG 인스턴스를 사용하거나, 네임스페이스 전략을 변경한 뒤 활성화하십시오.
+
 ## 서명 검증 (Signature Verification)
 
 HMAC-SHA256을 사용하여 웹훅 페이로드를 검증합니다.
@@ -95,11 +112,12 @@ HMAC-SHA256을 사용하여 웹훅 페이로드를 검증합니다.
 
 SIGINT/SIGTERM 수신 시:
 
-1. **HTTP 서버 종료** — 새로운 요청 수락 중단 (5초 타임아웃)
+1. **HTTP 서버 종료** — 새로운 요청 수락 중단 (`--webhook-shutdown-timeout`, 기본 30초)
 2. **동기화 컨텍스트 취소** — 진행 중인 복제/빌드 작업에 `context.Done()` 전달
-3. **워커 드레인(drain)** — SyncQueue 워커가 종료될 때까지 대기 (30초 타임아웃)
+3. **워커 드레인(drain)** — SyncQueue 워커가 종료될 때까지 대기 (`--webhook-shutdown-timeout`, 기본 30초)
 
 진행 중인 복제/빌드 작업은 컨텍스트 취소를 수신하고 즉시 중단되어 종료 대기 시간을 최소화합니다.
+종료가 시작된 뒤 새 웹훅 delivery가 들어오면 `503 Service Unavailable`을 반환하므로, provider가 성공 처리 대신 재시도할 수 있습니다.
 
 ## 파이프라인 (Pipeline)
 
@@ -201,6 +219,23 @@ include_paths:
 
 CCG는 현재 웹훅 운영을 위한 `/metrics` 엔드포인트를 제공하지 않습니다. `/status`를 주요 구조화된 런타임 뷰로 활용하십시오.
 
+### 복구 Runbook
+
+`/status`가 degraded 웹훅 동기화를 보고하거나, 큐 대기 시간이 계속 증가하거나, 배포 재시작 중 수락된 이벤트가 중단되었을 수 있을 때는 아래 절차를 사용하십시오.
+
+1. `/status.webhook.recent_repos`와 로그에서 `repo`, `branch`, `last_error`를 확인합니다.
+2. 잘못된 `.ccg.yaml` `include_paths`처럼 재시도 불가능한 저장소 설정 오류를 수정합니다.
+3. upstream provider가 복구를 주도해야 한다면 같은 브랜치에 새 push를 발생시킵니다.
+4. 수동 복구가 필요하면 checkout 디렉터리 기준으로 네임스페이스를 업데이트합니다.
+
+   ```bash
+   ccg update /data/repos/api --namespace api
+   ccg status --namespace api --errors
+   ```
+
+5. 검색, 커뮤니티, 저장된 flow가 여전히 오래된 것처럼 보이면 namespace `api`에 대해 필요한 postprocess 플래그와 함께 MCP `run_postprocess` 도구를 호출합니다.
+6. `/status`를 다시 확인합니다. 같은 저장소의 동기화가 성공하면 저장소별 unresolved error가 해제됩니다.
+
 배포 프로필, 데이터베이스 선택, 네임스페이스 크기 가이드 및 일반적인 실패 모드에 대해서는 [운영(Operations)](operations.md)을 참조하십시오.
 
 ## 패닉 복구 (Panic Recovery)

guide/operations.md

@@ -205,6 +205,21 @@ Webhook deployments should be configured with:
 - `--repo-root` on durable local storage
 - `--db-driver postgres` for team or always-on deployments
 
+Webhook namespace extraction uses the final repository name. For example,
+`acme/api` is stored in namespace `api` and checked out under
+`$REPO_ROOT/api`. This is intended for single-owner webhook deployments. If an
+allowlist spans multiple owners, the server logs a warning because `acme/api`
+and `external/api` would collide in the same namespace and checkout path.
+
+Recommended policy:
+
+- Use one organization/owner per webhook CCG instance.
+- Keep repo final names unique inside an instance.
+- Use separate CCG instances when different organizations may contain matching
+  repo names.
+- Treat `*/*` as a development or carefully isolated configuration, not a
+  normal production allowlist.
+
 SQLite webhook deployments default to one worker unless
 `--webhook-workers` or `CCG_WEBHOOK_WORKERS` is explicitly set. This avoids
 creating multiple concurrent writers against the same SQLite database. With
@@ -268,10 +283,26 @@ single event is roughly 46 minutes before it is abandoned.
 
 On SIGINT/SIGTERM:
 
-1. HTTP stops accepting new requests with a 5-second shutdown window.
+1. HTTP stops accepting new requests with `--webhook-shutdown-timeout` (default
+   30 seconds).
 2. The sync context is cancelled and in-progress clone/build work observes
    `context.Done()`.
-3. SyncQueue workers get up to 30 seconds to drain.
+3. SyncQueue workers get up to `--webhook-shutdown-timeout` to drain.
+
+Webhook deliveries received after queue shutdown starts return `503 Service
+Unavailable`, which lets GitHub/Gitea retry instead of treating the event as
+accepted. A request accepted immediately before shutdown can still be cancelled
+by process shutdown; recover it with a new push or a manual namespace update.
+
+Manual recovery:
+
+```bash
+ccg update /data/repos/api --namespace api
+ccg status --namespace api --errors
+```
+
+If search, communities, or saved flows still look stale, call the MCP
+`run_postprocess` tool for namespace `api` with the needed postprocess flags.
 
 The Streamable HTTP server does not use a fixed `WriteTimeout` because MCP
 streams can be long-lived. Put idle connection limits and request buffering

guide/webhook.md

@@ -82,6 +82,30 @@ Use the `--allow-repo` flag to configure allowed branches per repository.
 2. Rejected if no matching rule found
 3. `refs/heads/` prefix is automatically stripped from the `ref` field in webhook payload
 
+### Namespace Strategy and Single-Org Operation
+
+Webhook sync derives the graph namespace and checkout directory from the
+repository name portion of `org/repo`. For example, `acme/api` maps to the
+`api` namespace and `/data/repos/api` checkout.
+
+This keeps single-organization deployments short and predictable, which is the
+recommended operating model. If the allowlist spans multiple owners, such as
+`acme/*` plus `external/shared` or `*/*`, CCG logs a startup warning because
+repositories with the same final name can collide:
+
+| Repo | Derived namespace |
+|------|-------------------|
+| `acme/api` | `api` |
+| `external/api` | `api` |
+
+Operational policy:
+
+- Prefer one owner/organization per webhook CCG instance.
+- Do not allow two repositories with the same final repo name in the same
+  instance.
+- If multi-owner sync becomes necessary, run separate CCG instances or change
+  the namespace strategy before enabling those rules.
+
 ## Signature Verification
 
 Verifies webhook payload with HMAC-SHA256.
@@ -101,11 +125,12 @@ By default, webhook requests fail closed unless `--webhook-secret` is configured
 
 On SIGINT/SIGTERM:
 
-1. **HTTP server shutdown** — stops accepting new requests (5-second timeout)
+1. **HTTP server shutdown** — stops accepting new requests (`--webhook-shutdown-timeout`, default 30 seconds)
 2. **sync context cancel** — propagates `context.Done()` to in-progress clone/build operations
-3. **worker drain** — waits for SyncQueue workers to finish (30-second timeout)
+3. **worker drain** — waits for SyncQueue workers to finish (`--webhook-shutdown-timeout`, default 30 seconds)
 
 In-progress clone/build operations receive the context cancel and stop immediately, minimizing shutdown wait time.
+After shutdown begins, new webhook deliveries are rejected with `503 Service Unavailable` so providers can retry instead of treating the event as successfully accepted.
 
 ## Pipeline
 
@@ -234,6 +259,29 @@ same repo clears that repo's error state.
 CCG does not currently expose a `/metrics` endpoint for webhook operations.
 Treat `/status` as the primary structured runtime view.
 
+### Recovery Runbook
+
+Use this runbook when `/status` reports a degraded webhook sync, queue age keeps
+growing, or a deployment restart may have interrupted an accepted event.
+
+1. Check `/status.webhook.recent_repos` and logs for `repo`, `branch`, and
+   `last_error`.
+2. Fix non-retryable repository configuration failures, such as malformed
+   `.ccg.yaml` `include_paths`.
+3. Trigger a new push on the same branch when the upstream provider should
+   drive recovery.
+4. For manual recovery, update the namespace from the checkout directory:
+
+   ```bash
+   ccg update /data/repos/api --namespace api
+   ccg status --namespace api --errors
+   ```
+
+5. If search, communities, or saved flows still look stale, call the MCP
+   `run_postprocess` tool for namespace `api` with the needed postprocess flags.
+6. Recheck `/status`; a successful sync for the same repo clears the repo-level
+   unresolved error.
+
 For deployment profiles, database choice, namespace size guidance, and common
 failure modes, see [Operations](operations.md).
 

internal/analysis/deadcode/service.go

@@ -92,6 +92,9 @@ func (s *Service) FindPage(ctx context.Context, opts Options) (Result, error) {
 	return Result{Items: nodes, Pagination: paging.BuildPage(req, len(nodes), hasMore)}, nil
 }
 
+// normalizePathPrefix cleans a path prefix and returns an empty string if the cleaned result is ".".
+// @intent ensure path prefix filtering is consistent regardless of trailing slashes or "." input
+// @domainRule a path prefix of "." should be treated the same as an empty prefix (no filtering)
 func normalizePathPrefix(prefix string) string {
 	if prefix == "" {
 		return ""

internal/analysis/largefunc/service.go

@@ -94,6 +94,9 @@ func (s *Service) FindPage(ctx context.Context, opts Options) (Result, error) {
 	return Result{Items: nodes, Pagination: paging.BuildPage(req, len(nodes), hasMore)}, nil
 }
 
+// normalizePathPrefix cleans a path prefix and returns an empty string if the cleaned result is ".".
+// @intent ensure path prefix filtering is consistent regardless of trailing slashes or "." input
+// @domainRule a path prefix of "." should be treated the same as an empty prefix (no filtering)
 func normalizePathPrefix(prefix string) string {
 	if prefix == "" {
 		return ""

internal/server/serve.go

@@ -253,6 +253,12 @@ func RunStreamableHTTP(deps *cli.Deps, srv *mcpgo.MCPServer, cfg cli.ServeConfig
 		for _, s := range cfg.AllowRepo {
 			rules = append(rules, webhook.ParseRepoRule(s))
 		}
+		if spansMultipleOwners, owners := webhook.AllowRulesSpanMultipleOwners(rules); spansMultipleOwners {
+			deps.Logger.Warn("webhook allow-repo spans multiple owners; repo-name namespace strategy can collide for equal repo names",
+				"owners", owners,
+				"namespace_strategy", "repo_name",
+			)
+		}
 		filter := webhook.NewRepoFilterFromRules(rules)
 		secret := []byte(cfg.WebhookSecret)
 		repoLocker := webhook.NewRepoLocker(30 * time.Second)

internal/webhook/allowlist.go

@@ -3,6 +3,7 @@ package webhook
 
 import (
 	"path"
+	"sort"
 	"strings"
 )
 
@@ -153,6 +154,37 @@ func ParseRepoRule(s string) RepoRule {
 	return RepoRule{Pattern: pattern, Branches: branches}
 }
 
+// AllowRuleOwners returns the positive repository owner prefixes present in allow rules.
+// @intent let server startup warn when repo-name namespace extraction is used with multi-owner webhook allowlists.
+// @domainRule deny rules are ignored because they only narrow the positive admission surface.
+func AllowRuleOwners(rules []RepoRule) []string {
+	owners := make(map[string]struct{})
+	for _, rule := range rules {
+		pattern := strings.TrimSpace(rule.Pattern)
+		if pattern == "" || strings.HasPrefix(pattern, "!") {
+			continue
+		}
+		owner, _, ok := strings.Cut(pattern, "/")
+		if !ok || owner == "" {
+			continue
+		}
+		owners[owner] = struct{}{}
+	}
+	out := make([]string, 0, len(owners))
+	for owner := range owners {
+		out = append(out, owner)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// AllowRulesSpanMultipleOwners reports whether webhook rules admit repositories under more than one owner prefix.
+// @intent identify configurations that can collide under the current repo-name namespace strategy.
+func AllowRulesSpanMultipleOwners(rules []RepoRule) (bool, []string) {
+	owners := AllowRuleOwners(rules)
+	return len(owners) > 1 || (len(owners) == 1 && owners[0] == "*"), owners
+}
+
 // @intent apply one compiled allow or deny pattern to a repository full name during filter evaluation.
 func (r *allowRule) match(repoFullName string) bool {
 	if r.wildcard {