> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawsql.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.

# Troubleshoot CI/CD Integrations

> Diagnose webhook delivery, SQL collection, authentication, processing, gate, and feedback failures by symptom.

Start from the observed symptom, confirm the failure stage, and apply the matching remedy. A consistent stage-first diagnosis avoids chasing the wrong component.

## Goal

Diagnose webhook delivery, SQL collection, authentication, processing, gate, and feedback failures by symptom.

## Prerequisites

Start from the observed symptom and confirm which integration stage failed.

## Symptom reference

| Symptom                                    | Likely stage     | First checks                                            |
| ------------------------------------------ | ---------------- | ------------------------------------------------------- |
| Source reports delivery failure or timeout | Webhook delivery | Endpoint reachability, TLS, DNS, signature secret       |
| No review job is created                   | Filtering        | Repository, branch, path, and event scope               |
| Job uses the wrong SQL                     | SQL collection   | Diff selection, file extensions, removed files          |
| 401 or 403 during submission               | Authentication   | Credential scope, expiry, allowlist                     |
| Job stays queued or times out              | Processing       | Queue depth, service availability, context completeness |
| Gate blocks unexpectedly                   | Gate             | Policy version, thresholds, failure policy              |
| Result does not appear in the platform     | Feedback         | Permissions, status mapping, duplicate delivery         |

## Stage-by-stage diagnosis

### Webhook delivery

* Confirm the endpoint is reachable and accepts only the expected sources.
* Verify the shared secret or signing key matches on both sides.
* Check DNS, proxy, firewall, and TLS certificate validity.
* Inspect retries and delivery logs on the source platform.

### SQL collection

* Confirm the diff includes only new and modified SQL files.
* Verify path and extension filters, and that removed files are ignored.
* Check that the workspace dialect matches the SQL being reviewed.

### Authentication

* Confirm the credential is valid, unexpired, and scoped to the target.
* Verify that the endpoint allowlist includes the calling platform.
* Rotate the credential and re-run if the error persists.

### Processing

* Check that the workspace has the DDL or connection needed by the policy.
* Confirm the review policy is published and applicable.
* Look for parse errors caused by a dialect or script mismatch.

### Gate

* Confirm the applied policy version and blocking criteria are correct.
* Review the failure policy for timeout and unavailability cases.
* Inspect manual exceptions for scope, approver, and expiration.

### Feedback

* Verify the status or comment permissions on the source platform.
* Confirm the result targets the current revision.
* Check that duplicate delivery is not creating conflicting feedback.

## Expected Result

The failure is traced to a specific stage and the matching remedy from the stage-by-stage diagnosis is applied.

## Related

* [Webhook Integration Model](/en/user-guide/cicd/webhook)