> For the complete documentation index, see [llms.txt](https://docs.serverlessapigateway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serverlessapigateway.com/troubleshooting/wrangler-deploy-guide/docs-sync-and-canonical-examples.md).

# Docs Sync and Canonical Examples

Treat the checked-in config examples as the canonical source for both docs and automated checks. The gateway repo includes config examples that are used in both documentation and test fixtures. This page explains the sync process so documentation and tests always reference the same config shapes.

**Last reviewed:** 2026-03-06

## When to use this

Use the deployment and troubleshooting guides when you are deploying the gateway to Cloudflare, setting up CI/CD, running tests, or diagnosing production issues. These guides cover the operational side of the gateway lifecycle from local development to production debugging.

## Key concepts

* The gateway deploys as a standard Cloudflare Worker using `wrangler deploy`. The `wrangler.toml` file defines the worker name, entrypoint, compatibility settings, and binding declarations.
* GitHub Actions can automate deployments, running config validation, tests, and docs checks before publishing the worker. The workflow uses the same `wrangler deploy` command.
* The gateway repo includes Vitest unit tests and optional E2E tests using `unstable_dev`. Run unit tests with `npm test` and E2E tests with the `RUN_LOCAL_WORKER_E2E=true` flag.
* When debugging upstream failures, isolate whether the issue is in routing (wrong path matched), auth (token rejected), or the upstream itself (backend error). Check `wrangler tail` logs for the gateway's perspective.

## Repo-grounded example

```json
{
  "$schema": "./api-config.schema.json",
  "title": "Minimal Gateway",
  "cors": {
    "allow_origins": ["https://app.example.com"],
    "allow_methods": ["GET", "POST", "OPTIONS"],
    "allow_headers": ["Content-Type", "Authorization"],
    "expose_headers": ["X-Request-Id"],
    "allow_credentials": true,
    "max_age": 300
  },
  "paths": [
    {
      "method": "GET",
      "path": "/health",
      "response": { "status": "ok" }
    }
  ]
}
```

This snippet is one of the canonical config examples used in both docs and tests. When you change a config example, the docs generation script and test fixtures should be updated together to keep documentation accurate and tests passing.

## Troubleshooting

* If `wrangler deploy` fails with "missing binding", check your `wrangler.toml` for typos in binding names and verify that all referenced KV namespaces, service bindings, and secrets exist in your Cloudflare account.
* If GitHub Actions deploys succeed but the worker returns 500, check whether environment variables and secrets are set in the Cloudflare dashboard -- they are not deployed by Wrangler and must be configured separately.
* If E2E tests fail with "unstable\_dev not found", make sure you are running a Wrangler version that supports `unstable_dev` and that `RUN_LOCAL_WORKER_E2E=true` is set in your environment.
* If routes work locally but not in production, compare the config source: local dev uses the file system, while production may use KV or `SAG_API_CONFIG_JSON`. Confirm the production config matches your local config.

## Related docs

* [wrangler](/deployment/wrangler.md)
* [github actions](/deployment/github-actions.md)
* [gateway troubleshooting matrix](/troubleshooting/wrangler-deploy-guide/gateway-troubleshooting-matrix.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.serverlessapigateway.com/troubleshooting/wrangler-deploy-guide/docs-sync-and-canonical-examples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.