📚 Documentation Reconciliation Report - 2026-06-13

[github-actions]

Summary

Found 2 discrepancies between documentation and implementation during nightly reconciliation check.

• Workflow Run: §27481708575
• Date: 2026-06-13
• Branch: main

---

Important Issues 🟡

1. GH_AW_OTLP_ENDPOINTS is missing from user-facing documentation

Location: README.md (Tracing section, ~line 79) and docs/ENVIRONMENT_VARIABLES.md (OpenTelemetry/Tracing Variables section, ends at line 138)
Problem: The GH_AW_OTLP_ENDPOINTS environment variable is fully implemented but absent from both README.md and docs/ENVIRONMENT_VARIABLES.md. The only documentation is in AGENTS.md (the internal agent instruction file), which is not user-facing.
Actual Behavior: GH_AW_OTLP_ENDPOINTS enables multi-backend OTLP fan-out tracing. It supports two formats:

• Comma-separated URLs: "(otel1.example.com/redacted),(otel2.example.com/redacted)"
• JSON array with per-endpoint headers: [{"url":"(otel1.example.com/redacted)","headers":"Authorization=Bearer token"}]

When set, spans are exported to ALL listed endpoints (partial-failure tolerant). Takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT. Shared headers from OTEL_EXPORTER_OTLP_HEADERS / config apply to comma-separated entries.
Impact: Users who need multi-backend tracing (e.g., sending traces to both an internal observability stack and an external platform) cannot discover this feature.
Suggested Fix:

1. Add GH_AW_OTLP_ENDPOINTS to the Tracing table in README.md under the existing OTel variables.
2. Add GH_AW_OTLP_ENDPOINTS to docs/ENVIRONMENT_VARIABLES.md in the "OpenTelemetry / Tracing Variables" section.
   Code Reference: internal/tracing/config_resolver.go:149 (resolveExtraEndpoints), internal/tracing/provider.go (fan-out exporter)

Suggested README.md row to add:

| `GH_AW_OTLP_ENDPOINTS` | Comma-separated OTLP URLs (or JSON array with per-endpoint `headers`) for multi-backend fan-out; all listed endpoints receive every span. Takes precedence over `OTEL_EXPORTER_OTLP_ENDPOINT`. |

---

Minor Issues 🔵

2. internal/sanitize/ package missing from CONTRIBUTING.md project structure

Location: CONTRIBUTING.md, project structure tree (line ~281) and "Key Directories" section (line ~306)
Problem: The internal/sanitize/ package exists in the codebase and is actively used (imported by internal/envutil/github.go for URL and token redaction in logs), but it is not listed in either the project structure diagram or the Key Directories descriptions.
Actual Behavior: The package provides SanitizeString(), SanitizeJSON(), TruncateSecret(), and TruncateSecretMap() for redacting sensitive information (API keys, tokens, passwords) from log output.
Impact: New contributors are unaware of the sanitize utilities and may implement duplicate redaction logic or accidentally log secrets.
Suggested Fix: Add sanitize/ to the project tree and Key Directories in CONTRIBUTING.md:

In the project structure tree, add:

│   ├── sanitize/              # Sensitive data redaction utilities for logging

In the Key Directories section, add:

- **`internal/sanitize/`** - Sensitive data redaction utilities (SanitizeString, SanitizeJSON, TruncateSecret) for safe log output

Code Reference: internal/sanitize/sanitize.go, internal/envutil/github.go:10 (import)

---

Documentation Completeness

Missing Documentation

• GH_AW_OTLP_ENDPOINTS is implemented but not documented in user-facing docs
• internal/sanitize/ package exists but is absent from CONTRIBUTING.md project structure

Accurate Sections ✅

• Quick Start JSON config — mcpServers, gateway.agentId, type, container, env fields all verified against internal/config/config_stdin.go
• Docker run command — env vars, volume mounts, port mapping verified against run_containerized.sh and flags_core.go
• Go version requirement (1.25.0) — matches go.mod line 3
• Make targets — all targets (build, test, test-unit, test-integration, test-all, lint, coverage, install, format, clean) verified against Makefile
• make install description — accurately describes Go check, golangci-lint install, and dependency download steps
• Default listen address (127.0.0.1:3000) — verified in internal/cmd/root.go (DefaultListenIPv4 = "127.0.0.1", DefaultListenPort = "3000")
• GitHub token priority order (GITHUB_MCP_SERVER_TOKEN → GITHUB_TOKEN → GITHUB_PERSONAL_ACCESS_TOKEN → GH_TOKEN) — verified in internal/envutil/github.go:29
• GET /health endpoint — implemented in internal/server/health.go with documented JSON shape
• GET /reflect endpoint — implemented in internal/server/handlers.go
• run.sh default port 8000 and routed mode — verified in run.sh (PORT="${MCP_GATEWAY_PORT:-${PORT:-8000}}", MODE="${MODE:---routed}")
• --config-stdin auto-added by run_containerized.sh — verified in run_containerized.sh:344
• TOML field names (agent_id, tool_timeout, startup_timeout, keepalive_interval) — verified in internal/config/config_core.go
• JSON stdin field names (agentId, toolTimeout, payloadDir, trustedBots) — verified in internal/config/config_stdin.go
• command not supported in JSON stdin format — verified; StdinServerConfig has no Command field (internal/config/config_stdin.go:109)
• Environment variable defaults — all default values in ENVIRONMENT_VARIABLES.md verified against code

Tested Commands

• ✅ make build — target exists and is correctly described; blocked only by network restrictions in nightly environment
• ✅ make test / make test-unit — aliases verified in Makefile; correctly described as no-build-required
• ✅ make test-integration — verified auto-builds binary when absent
• ✅ make test-all — verified runs build dependency first
• ✅ make lint — verified runs go vet, gofmt, golangci-lint
• ✅ make coverage — verified produces coverage.out
• ✅ make install — verified installs golangci-lint and downloads Go modules
• ✅ make clean — verified removes awmg, coverage.out, test-result-unit.json
• ✅ make format — verified runs gofmt -w .

Recommendations

Immediate Actions:

1. Add GH_AW_OTLP_ENDPOINTS to the README.md Tracing table and to docs/ENVIRONMENT_VARIABLES.md
2. Add internal/sanitize/ to CONTRIBUTING.md project structure tree and Key Directories list

Nice to Have:

1. Document the JSON array format for GH_AW_OTLP_ENDPOINTS (currently underdocumented even in AGENTS.md)

Code References

• Tracing config resolver: internal/tracing/config_resolver.go
• Sanitize utilities: internal/sanitize/sanitize.go
• Token lookup: internal/envutil/github.go
• CLI flags: internal/cmd/flags_core.go, flags_logging.go, flags_tls.go, tracing.go
• Config core types: internal/config/config_core.go
• Config stdin types: internal/config/config_stdin.go

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Nightly Documentation Reconciler · 1K AIC · ⊞ 32K · ◷

• expires on Jun 16, 2026, 11:09 PM UTC