docs(docs): update config examples and automate generated refs sync

.github/workflows/docs-generated-sync.yml

@@ -0,0 +1,81 @@
+# Regenerates docs/generated after every push to main. If outputs drift, opens or
+# updates PR branch chore/docs-generated-sync (peter-evans/create-pull-request).
+# Also notifies convoy-website via repository_dispatch (event_type convoy_docs_sync).
+#
+# Cross-repo dispatch requires repository secret CONVOY_WEBSITE_DISPATCH_TOKEN on this
+# repo (see docs/generated/README.md). The token must be allowed to create repository
+# dispatch events on ${{ github.repository_owner }}/convoy-website (same org/user as
+# this repository is assumed).
+# Scope: only paths under add-paths are committed (currently docs/generated/**).
+name: Sync generated docs references
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: docs-generated-sync-${{ github.repository }}
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Set up Go
+        uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6
+        with:
+          go-version: "1.25.7"
+
+      - name: Cache Go modules
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-docs-generated-${{ hashFiles('go.sum') }}
+
+      - name: Download modules
+        run: go mod download
+
+      - name: Regenerate reference artifacts
+        run: make docs-generated
+
+      - name: Open or update PR when drift exists
+        uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6
+        with:
+          commit-message: "chore(docs): sync generated reference artifacts"
+          title: "chore(docs): sync generated reference artifacts"
+          body: |
+            This PR was opened automatically because `make docs-generated` produced changes under `docs/generated/` after a push to `main`.
+
+            **What to do:** Review the diff; if it matches the config/CLI changes on `main`, merge to clear drift.
+
+            **Branch:** `chore/docs-generated-sync` is reused and force-updated when new drift appears.
+
+            If `make docs-generated` starts writing additional paths (for example example config files), extend the workflow `add-paths` list in `.github/workflows/docs-generated-sync.yml`.
+          branch: chore/docs-generated-sync
+          base: main
+          delete-branch: false
+          add-paths: |
+            docs/generated/**
+
+  notify-convoy-website:
+    name: Notify convoy-website (repository_dispatch)
+    needs: sync
+    runs-on: ubuntu-latest
+    # Does not use GITHUB_TOKEN; dispatch uses CONVOY_WEBSITE_DISPATCH_TOKEN only.
+    permissions: {}
+    steps:
+      - name: Dispatch convoy_docs_sync
+        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
+        with:
+          token: ${{ secrets.CONVOY_WEBSITE_DISPATCH_TOKEN }}
+          repository: ${{ github.repository_owner }}/convoy-website
+          event-type: convoy_docs_sync
+          client-payload: '{"convoy_ref":"${{ github.sha }}"}'

Makefile

@@ -105,5 +105,11 @@ migrate_create:
 generate_docs:
 	swag init --generatedTime --parseDependency --parseInternal -d api/ api/*
 
+.PHONY: docs-generated
+docs-generated:
+	@mkdir -p docs/generated
+	go run ./scripts/docs/genconfigref -output docs/generated/config-reference.json
+	go run ./scripts/docs/gencliref -output docs/generated/cli-reference.json
+
 run_dependencies:
 	docker compose -f docker-compose.dep.yml up -d

convoy.env.example

@@ -1,64 +1,184 @@
-CONVOY_ENV=development
-CONVOY_HOST=http://localhost:5005
-CONVOY_ROOT_PATH=
-
-# Root path for path-based routing behind load balancers
-# Example: CONVOY_ROOT_PATH=/convoy
-# This allows you to access Convoy at https://yourdomain.com/convoy
+# Overrides for config loaded from JSON. Variable names match `envconfig` tags on
+# `config.Configuration` (see config/config.go); `envconfig.Process` uses prefix `convoy`.
 
-CONVOY_DB_TYPE=mongodb
-CONVOY_DB_DSN=mongodb://localhost:27017/convoy
+# --- Core ---
+CONVOY_API_VERSION=2025-11-24
+CONVOY_ENV=oss
+CONVOY_HOST=localhost:5005
+CONVOY_ROOT_PATH=
+CONVOY_CUSTOM_DOMAIN_SUFFIX=
+CONVOY_MAX_RESPONSE_SIZE=50
+CONVOY_CONSUMER_POOL_SIZE=100
+CONVOY_INSTANCE_INGEST_RATE=1000
+CONVOY_API_RATE_LIMIT=1000
+CONVOY_WORKER_EXECUTION_MODE=default
+CONVOY_MAX_RETRY_SECONDS=0
+CONVOY_ENABLE_FEATURE_FLAG=
+CONVOY_ENABLE_PROFILING=false
+CONVOY_LICENSE_KEY=
+CONVOY_LICENSE_SERVICE_HOST=
+CONVOY_LICENSE_SERVICE_VALIDATE_ENDPOINT=
+CONVOY_LICENSE_SERVICE_TIMEOUT=0s
+CONVOY_LICENSE_SERVICE_RETRY_COUNT=0
 
-CONVOY_SENTRY_DSN=
-CONVOY_SENTRY_SAMPLE_RATE=0.1
-CONVOY_SENTRY_DEBUG=false
+# --- HTTP server (tags SSL, PORT, etc.; no CONVOY_ prefix) ---
+SSL=false
+PORT=5005
+WORKER_PORT=5006
+AGENT_PORT=5008
+INGEST_PORT=5009
+SOCKET_PORT=0
+DOMAIN_PORT=0
+HTTP_PROXY=
+CONVOY_SSL_CERT_FILE=
+CONVOY_SSL_KEY_FILE=
 
-CONVOY_MUTIPLE_TENANTS=false
+# --- Database (Postgres) ---
+CONVOY_DB_TYPE=postgres
+CONVOY_DB_SCHEME=postgres
+CONVOY_DB_HOST=localhost
+CONVOY_DB_USERNAME=postgres
+CONVOY_DB_PASSWORD=postgres
+CONVOY_DB_DATABASE=convoy
+CONVOY_DB_OPTIONS=sslmode=disable&connect_timeout=30
+CONVOY_DB_PORT=5432
+CONVOY_DB_DSN=
+CONVOY_DB_MAX_OPEN_CONN=0
+CONVOY_DB_MAX_IDLE_CONN=0
+CONVOY_DB_CONN_MAX_LIFETIME=3600
+# JSON array of database objects; only used with read-replica feature where supported
+CONVOY_DB_READ_REPLICAS=
 
-CONVOY_LIMITER_PROVIDER=redis
-CONVOY_CACHE_PROVIDER=redis
-CONVOY_QUEUE_PROVIDER=redis
-CONVOY_REDIS_DSN=redis://localhost:6379
+# --- Redis ---
+CONVOY_REDIS_SCHEME=redis
+CONVOY_REDIS_HOST=localhost
+CONVOY_REDIS_USERNAME=
+CONVOY_REDIS_PASSWORD=
+CONVOY_REDIS_DATABASE=
+CONVOY_REDIS_PORT=6379
+CONVOY_REDIS_CLUSTER_ADDRESSES=
+CONVOY_REDIS_SENTINEL_MASTER_NAME=
 CONVOY_REDIS_SENTINEL_USERNAME=
 CONVOY_REDIS_SENTINEL_PASSWORD=
+CONVOY_REDIS_TLS_SKIP_VERIFY=false
+CONVOY_REDIS_TLS_CERT_FILE=
+CONVOY_REDIS_TLS_KEY_FILE=
+CONVOY_REDIS_TLS_CA_CERT_FILE=
 
-CONVOY_LOGGER_LEVEL=info
-CONVOY_LOGGER_PROVIDER=console
+# --- Prometheus (queue / Asynq metrics address) ---
+CONVOY_PROM_DSN=
 
-SSL=false
-PORT=5005
-WORKER_PORT=5006
-CONVOY_SSL_KEY_FILE=
-CONVOY_SSL_CERT_FILE=
-
-CONVOY_STRATEGY_TYPE=default
-CONVOY_SIGNATURE_HASH=SHA512
-CONVOY_DISABLE_ENDPOINT=false
-CONVOY_SIGNATURE_HEADER=X-Convoy-Signature
-CONVOY_INTERVAL_SECONDS=10
-CONVOY_RETRY_LIMIT=10
-
-CONVOY_SMTP_PROVIDER=sendgrid
-CONVOY_SMTP_URL=smtp.sendgrid.net
-CONVOY_SMTP_USERNAME=sendgrid-username
-CONVOY_SMTP_PASSWORD=sendgrid-password
-CONVOY_SMTP_FROM=support@frain.dev
-CONVOY_SMTP_PORT=2525
-CONVOY_SMTP_REPLY_TO=support@frain.dev
-
-CONVOY_NEWRELIC_APP_NAME=
-CONVOY_NEWRELIC_LICENSE_KEY=
-CONVOY_NEWRELIC_CONFIG_ENABLED=false
-CONVOY_NEWRELIC_DISTRIBUTED_TRACER_ENABLED=false
-
-CONVOY_REQUIRE_AUTH=false
-CONVOY_BASIC_AUTH_CONFIG="[{\"username\": \"some-admin\",\"password\": \"some-password\",\"role\": {\"type\": \"super_user\",\"groups\": []}}]"
-CONVOY_API_KEY_CONFIG="[{\"api_key\":\"ABC1234\",\"role\":{\"type\":\"admin\",\"groups\":[\"group-uid-1\",\"group-uid-2\"],\"apps\":[\"apps-uid-1\",\"apps-uid-2\"]}}]"
+# --- Logger ---
+CONVOY_LOGGER_LEVEL=error
 
+# --- Auth realms ---
+CONVOY_SIGNUP_ENABLED=true
 CONVOY_NATIVE_REALM_ENABLED=true
-
+CONVOY_PORTAL_REALM_ENABLED=true
 CONVOY_JWT_REALM_ENABLED=true
 CONVOY_JWT_SECRET=
-CONVOY_JWT_EXPIRY=
+CONVOY_JWT_EXPIRY=3600
 CONVOY_JWT_REFRESH_SECRET=
-CONVOY_JWT_REFRESH_EXPIRY=
+CONVOY_JWT_REFRESH_EXPIRY=86400
+CONVOY_GOOGLE_OAUTH_ENABLED=false
+CONVOY_GOOGLE_OAUTH_CLIENT_ID=
+CONVOY_GOOGLE_OAUTH_REDIRECT_URL=
+CONVOY_SSO_ENABLED=false
+CONVOY_SSO_REDIRECT_URL=
+# JSON arrays; file realm for dashboard basic / API key auth
+CONVOY_BASIC_AUTH_CONFIG=
+CONVOY_API_KEY_CONFIG=
+
+# --- SMTP ---
+CONVOY_SMTP_SSL=false
+CONVOY_SMTP_PROVIDER=
+CONVOY_SMTP_URL=
+CONVOY_SMTP_PORT=587
+CONVOY_SMTP_USERNAME=
+CONVOY_SMTP_PASSWORD=
+CONVOY_SMTP_FROM=
+CONVOY_SMTP_REPLY_TO=
+
+# --- Tracing ---
+CONVOY_TRACER_PROVIDER=
+CONVOY_OTEL_SAMPLE_RATE=1
+CONVOY_OTEL_COLLECTOR_URL=
+CONVOY_OTEL_INSECURE_SKIP_VERIFY=true
+CONVOY_OTEL_AUTH_HEADER_NAME=
+CONVOY_OTEL_AUTH_HEADER_VALUE=
+CONVOY_SENTRY_DSN=
+CONVOY_SENTRY_SAMPLE_RATE=0
+CONVOY_SENTRY_DEBUG=false
+CONVOY_SENTRY_ENVIRONMENT=
+CONVOY_DATADOG_AGENT_URL=
+
+# --- Retention & circuit breaker ---
+CONVOY_RETENTION_POLICY=720h
+CONVOY_RETENTION_POLICY_ENABLED=false
+CONVOY_CIRCUIT_BREAKER_SAMPLE_RATE=30
+CONVOY_CIRCUIT_BREAKER_ERROR_TIMEOUT=30
+CONVOY_CIRCUIT_BREAKER_FAILURE_THRESHOLD=70
+CONVOY_CIRCUIT_BREAKER_SUCCESS_THRESHOLD=5
+CONVOY_CIRCUIT_BREAKER_MINIMUM_REQUEST_COUNT=10
+CONVOY_CIRCUIT_BREAKER_OBSERVABILITY_WINDOW=5
+CONVOY_CIRCUIT_BREAKER_CONSECUTIVE_FAILURE_THRESHOLD=10
+CONVOY_CIRCUIT_BREAKER_SKIP_SLEEP=false
+
+# --- Analytics & storage ---
+CONVOY_ANALYTICS_ENABLED=true
+CONVOY_STORAGE_POLICY_TYPE=on-prem
+CONVOY_STORAGE_AWS_PREFIX=
+CONVOY_STORAGE_AWS_BUCKET=
+CONVOY_STORAGE_AWS_ACCESS_KEY=
+CONVOY_STORAGE_AWS_SECRET_KEY=
+CONVOY_STORAGE_AWS_REGION=
+CONVOY_STORAGE_AWS_SESSION_TOKEN=
+CONVOY_STORAGE_AWS_ENDPOINT=
+CONVOY_STORAGE_PREM_PATH=
+
+# --- Metrics (Prometheus backend when enabled) ---
+CONVOY_METRICS_ENABLED=false
+CONVOY_METRICS_BACKEND=prometheus
+CONVOY_METRICS_SAMPLE_TIME=5
+CONVOY_METRICS_QUERY_TIMEOUT=30
+CONVOY_METRICS_MATERIALIZED_VIEW_REFRESH_INTERVAL=2
+
+# --- Pyroscope ---
+CONVOY_ENABLE_PYROSCOPE_PROFILING=false
+CONVOY_PYROSCOPE_URL=
+CONVOY_PYROSCOPE_USERNAME=
+CONVOY_PYROSCOPE_PASSWORD=
+CONVOY_PYROSCOPE_PROFILE_ID=
+
+# --- Dispatcher outbound (CIDR lists comma-separated for slices) ---
+CONVOY_DISPATCHER_INSECURE_SKIP_VERIFY=false
+CONVOY_DISPATCHER_ALLOW_LIST=0.0.0.0/0,::/0
+CONVOY_DISPATCHER_BLOCK_LIST=127.0.0.0/8,::1/128
+CONVOY_DISPATCHER_CACERT_PATH=
+CONVOY_DISPATCHER_CACERT_STRING=
+CONVOY_DISPATCHER_PING_METHODS=HEAD,GET,POST
+CONVOY_DISPATCHER_SKIP_PING_VALIDATION=false
+
+# --- SSO service (Convoy Cloud / Overwatch integration) ---
+CONVOY_SSO_SERVICE_HOST=https://overwatch.getconvoy.cloud
+CONVOY_SSO_SERVICE_REDIRECT_PATH=/sso/redirect
+CONVOY_SSO_SERVICE_TOKEN_PATH=/sso/token
+CONVOY_SSO_SERVICE_ADMIN_PORTAL_PATH=/sso/admin-portal
+CONVOY_SSO_SERVICE_TIMEOUT=10s
+CONVOY_SSO_SERVICE_RETRY_COUNT=3
+
+# --- Billing ---
+CONVOY_BILLING_ENABLED=false
+CONVOY_BILLING_URL=
+CONVOY_BILLING_API_KEY=
+CONVOY_BILLING_ORGANISATION_HOST=
+CONVOY_PAYMENT_PROVIDER_TYPE=
+CONVOY_PAYMENT_PROVIDER_PUBLISHABLE_KEY=
+
+# --- HCP Vault (optional secrets) ---
+CONVOY_HCP_CLIENT_ID=
+CONVOY_HCP_CLIENT_SECRET=
+CONVOY_HCP_ORG_ID=
+CONVOY_HCP_PROJECT_ID=
+CONVOY_HCP_APP_NAME=
+CONVOY_HCP_SECRET_NAME=