{"owner":"envoyproxy","repo":"envoy","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".github/copilot-instructions.md"],"files":{"AGENTS.md":"# AGENTS.md\n\nInstructions for AI coding agents (Claude Code, Copilot, Cursor, etc.) working in this repository.\n\n## Critical rules\n\n1. **Always sign off commits.** The human user must sign off commits via `git commit -s` — never\n   manually write a `Signed-off-by` trailer. The sign-off attests that the committer (the user)\n   has the right to submit the code under the project's license.\n2. **Always run format and lint checks before committing.** Use `tools/local_fix_format.sh` for\n   a quick local check, or run `./ci/do_ci.sh format` inside Docker for the full CI check suite.\n   Format failures are the most common CI rejection. If running checks is impractical, warn the\n   user that formatting has not been verified.\n3. **Never amend commits or force-push after a PR has received human review.** Always create new\n   commits to preserve review history.\n4. **Never rebase a PR that is under review.** Use `git merge main` instead to pull in recent\n   changes. The project squash-merges, so commit count does not matter.\n5. **Disclose AI usage.** When submitting PRs, include a note about AI assistance in the PR\n   description. The submitter must fully understand all code being submitted.\n6. **Never commit to `main`.** Always create a new branch before committing. If switching\n   contexts or unsure which branch to use, ask the user.\n7. **Always push to a personal fork.** Do not create branches in the main repo.\n\n## Developer workflow\n\n### 1. Before starting work\n\nRead `CONTRIBUTING.md` for the full contribution process. Key points:\n- **Major features (>100 LOC or user-facing):** Open a GitHub issue first to discuss design.\n  For new extensions, read `EXTENSION_POLICY.md`.\n- **Small patches and bug fixes:** No prior communication needed.\n- Install git hooks: `./support/bootstrap`\n\n### 2. Writing code\n\nRead `STYLE.md` for the C++ coding style. After writing C++ code, run `clang-format` to fix\nformatting automatically rather than trying to hand-format:\n\n```bash\nclang-format -i <file>\n```\n\nTests must:\n- Live in `test/` mirroring the `source/` structure\n- Achieve 100% coverage for new code\n- Use `StrictMock` by default, `SimulatedTimeSystem` for time, port 0 for network\n- Unit tests must be hermetic and deterministic — no real time, no randomness\n- Integration tests (in `test/integration/`) use real network on localhost\n\n### 3. Building and testing\n\nSee `bazel/README.md` for full build documentation. Common commands:\n\n```bash\n# Docker-based (recommended — matches CI environment)\n./ci/run_envoy_docker.sh bash                                   # interactive shell\n./ci/do_ci.sh debug //test/common/http/...                      # build + test\n./ci/do_ci.sh debug.server_only                                 # build binary only\n\n# Local (requires local dependencies)\nbazel test -c dbg //test/common/http/...                         # run tests\nbazel build --config=clang -c opt //source/exe:envoy-static      # optimized binary\n```\n\nSanitizers, coverage, GDB debugging, and profiling are resource-intensive. Do **not** run\nthem unless the user explicitly asks. See `bazel/README.md` and `bazel/PPROF.md`.\n\n### 4. Format and lint checks (required before every commit)\n\nFormat failures are the most common CI rejection. Agents should produce content that conforms\nto the repo's style conventions for all file types (C++, BUILD, YAML, Markdown, shell, etc.).\n\n**Quick local check (recommended):**\n\n```bash\ntools/local_fix_format.sh          # uncommitted changes (default)\ntools/local_fix_format.sh -main    # changes since main\ntools/local_fix_format.sh -all     # entire repo\n```\n\n**Individual checks:**\n\n```bash\nbazel run //tools/code_format:check_format -- fix      # C++, BUILD, .bzl, .proto\nbazel run //tools/spelling:check_spelling_pedantic -- fix   # spelling\n./ci/do_ci.sh format                                   # full CI check (inside Docker)\n```\n\n**Linter config files — read these to produce compliant output without running the tools:**\n\n| Config file | What it configures |\n|-------------|--------------------|\n| `.clang-format` | C++/Proto formatting (100-col, include order, pointer alignment) |\n| `.yamllint` | YAML rules (140-col max, consistent indentation) |\n| `.flake8` | Python lint rules |\n| `rustfmt.toml` | Rust formatting (100-col, 2-space indent) |\n| `tools/spelling/spelling_dictionary.txt` | Custom word list (1700+ project terms) |\n\n### 5. Creating the commit\n\nBefore your first commit in a session:\n\n1. Check if the local `main` is up to date with `origin/main`:\n   ```bash\n   git fetch origin\n   git log main..origin/main --oneline\n   ```\n2. If `main` is behind, sync it:\n   ```bash\n   git checkout main && git pull && git checkout -\n   ```\n3. Create a new branch off the updated `main`:\n   ```bash\n   git checkout -b <descriptive-branch-name>\n   ```\n4. If you had uncommitted changes that conflict with the updated `main`, ask the user whether\n   to proceed on the outdated base or resolve conflicts against the new `main`.\n\nIf you're switching contexts or unsure which branch to commit to, ask the user before committing.\n\n```bash\ngit add <files>\ngit commit -s    # -s adds Signed-off-by automatically; NEVER write it manually\n```\n\n### 6. Pushing and creating a PR\n\n**PR title format** — lower-case subsystem prefix followed by a colon:\n`docs: fix grammar error`, `router: add x-envoy-overloaded header`\n\n**PR description template** — every PR must fill in:\n\n```\nCommit Message: <what this PR does — used as the final squash-merge message>\nAdditional Description: <context useful to reviewers>\nRisk Level: Low | Medium | High\nTesting: <what testing was done>\nDocs Changes: <description or N/A>\nRelease Notes: <description or N/A>\n```\n\nSee `PULL_REQUESTS.md` for full field descriptions and optional fields (runtime guard,\ndeprecation, platform-specific features).\n\n**Release notes:** User-facing changes **must** add a release note fragment under\n`changelogs/current/`. Name the file `<area>__<short-description>.rst`.\n\n### 7. Waiting for CI and review\n\n- Do **not** create draft PRs if you want prompt reviews — draft PRs are not triaged.\n- To re-run failed CI tasks, add a `/retest` comment on the PR.\n- PRs with no activity for 14+ days may be closed.\n\n### 8. Addressing review comments\n\n- **Never amend or force-push** after a reviewer has looked at the PR. Create new commits.\n- **Never rebase.** If you need to incorporate upstream changes:\n  ```bash\n  git fetch origin main && git merge origin/main\n  ```\n- If the reviewer asked for a runtime guard, add one (see `CONTRIBUTING.md`).\n\n### 9. After merge\n\nThe project squash-merges PRs. The \"Commit Message\" field in your PR description becomes the\nfinal commit message. Make sure it's up to date before merge.\n\n## Understanding CI\n\nEnvoy uses a checks-based CI system. Results appear as **GitHub Check Runs** on PRs, not as\nsimple workflow pass/fail statuses.\n\n**CI pipeline:**\n\n1. **`Envoy/Prechecks`** — fast checks: format/lint/spelling, dependency validation, docs build\n2. **`Envoy/Checks`** — heavier checks: compilation, tests, coverage, sanitizers\n\n**Checking CI status:**\n\n```bash\ngh pr checks <PR-number>\ngh run view <run-id> --log-failed\n```\n\nWhen CI fails, check the failed check run name to determine which `do_ci.sh` target to\nreproduce locally. Format failures come from `Envoy/Prechecks`; build/test failures come\nfrom `Envoy/Checks`.\n\n## Inclusive language\n\nThe following terms are **not allowed**:\n- ~~whitelist~~ -> allowlist\n- ~~blacklist~~ -> denylist / blocklist\n- ~~master~~ -> primary / main\n- ~~slave~~ -> secondary / replica\n\n## BUILD file conventions\n\nSee `bazel/DEVELOPER.md` for full BUILD file rules. Key points:\n- Use `envoy_cc_library`, `envoy_cc_test`, `envoy_cc_mock` (not raw `cc_library`)\n- Target suffixes: `_lib`, `_test`, `_mocks`, `_interface`\n- Every `#include` must have a corresponding `deps` entry\n\n## Updating dependencies\n\nSee `bazel/EXTERNAL_DEPS.md` and `DEPENDENCY_POLICY.md`. When updating a version:\n1. Update version, sha256, and urls in `bazel/repository_locations.bzl`\n2. Update `release_date` in `bazel/deps.yaml` to the UTC date of the new release\n3. Prefer maintainer-provided tarballs over GitHub auto-generated ones\n\n## CI and GitHub Actions (for workflow file authors)\n\n- In `if:` conditions, do **not** wrap expressions in `${{ }}` — the `if` field evaluates\n  expressions implicitly. Use `${{ }}` only in string contexts (`run:`, `with:`, `env:`).\n- Workflow files in `.github/workflows/` are shared across all branches (main and stable release\n  branches). Do not remove variables or inputs still referenced by stable branches.\n\n## Key files\n\n| File | Purpose |\n|------|---------|\n| `STYLE.md` | C++ coding style and error handling |\n| `CONTRIBUTING.md` | Contribution guidelines, deprecation, breaking changes |\n| `PULL_REQUESTS.md` | PR field descriptions |\n| `EXTENSION_POLICY.md` | Extension lifecycle and requirements |\n| `DEPENDENCY_POLICY.md` | External dependency rules |\n| `RELEASES.md` | Release schedule and backport process |\n| `SECURITY.md` | Security reporting and disclosure |\n| `REPO_LAYOUT.md` | Repository structure |\n| `bazel/README.md` | Building, testing, sanitizers, coverage |\n| `bazel/DEVELOPER.md` | BUILD file conventions |\n| `bazel/EXTERNAL_DEPS.md` | Managing external dependencies |\n| `bazel/PPROF.md` | Performance profiling |\n| `source/extensions/extensions_metadata.yaml` | Extension status and security posture |\n| `source/common/runtime/runtime_features.cc` | Runtime feature flag defaults |\n",".github/copilot-instructions.md":"# GitHub Copilot instructions for envoyproxy/envoy\n\n**Note:** These instructions are specifically for GitHub Copilot's agent/workspace environment, not for developers using Copilot in VS Code or other IDEs. For general development setup, see [DEVELOPER.md](https://github.com/envoyproxy/envoy/blob/main/DEVELOPER.md).\n\n## Repository overview\n\nThis repository contains the Envoy proxy, a cloud-native high-performance edge/middle/service proxy. It includes:\n\n- **source/** - Core C++ implementation of Envoy proxy\n- **test/** - Comprehensive test suite including unit, integration, and performance tests\n- **api/** - Protocol buffer definitions for Envoy's APIs (xDS, filters, etc.)\n- **bazel/** - Bazel build configurations, rules, and toolchain definitions\n- **contrib/** - Community-contributed extensions\n- **mobile/** - Envoy Mobile implementation\n- **tools/** - Development tooling, scripts, and utilities\n- **docs/** - Documentation source files\n\n## Build system\n\nThis repository uses **Bazel** as its primary build system.\n\n### Running Bazel commands in Copilot's local environment\n\n**IMPORTANT:** The key capability for GitHub Copilot is to run Bazel commands directly in the local workspace to build, test, and validate changes.\n**IMPORTANT:** You MUST run `/tmp/fix-bazel-truststore.sh` before the first time you issue a bazel command!!!\n**IMPORTANT:** Many bazel targets will be very slow/expensive to run/build/test - only test with bazel when told to.\n\n### Bazel configuration files\n\n- `.bazelrc` - Repository-wide Bazel configuration with build flags and platform settings\n- `user.bazelrc` - Optional user-specific overrides (gitignored)\n- `.bazelversion` - Specifies the exact Bazel version to use\n- `MODULE.bazel` / `WORKSPACE` - Dependency definitions (using bzlmod and WORKSPACE modes)\n\n### Compiler configuration\n\nEnvoy supports multiple compiler configurations. **Use `--config=clang` by default** unless told otherwise:\n\n```bash\n# Use Clang with libc++ (recommended, use by default)\nbazel build --config=clang //source/exe:envoy-static\n\n# Use GCC with libstdc++ (only if explicitly requested)\nbazel build --config=gcc //source/exe:envoy-static\n```\n\n## Language and coding standards\n\n### C++\n\n- **Primary Language:** Modern C++ (C++20)\n- **Compiler Requirements:** Clang >= 18 or GCC >= 13\n- **Standard Library:** libc++ (with Clang) or libstdc++ (with GCC)\n- **Style Guide:** See [STYLE.md](https://github.com/envoyproxy/envoy/blob/main/STYLE.md) for comprehensive coding standards\n\n## Testing\n\n### Running tests\n\n```bash\n# Run all tests\nbazel test --config=clang //test/...\n\n# Run tests in a specific directory\nbazel test --config=clang //test/common/http/...\n\n# Run a single test target\nbazel test --config=clang //test/common/http:async_client_impl_test\n\n# Run tests with additional logging\nbazel test --config=clang --test_output=streamed //test/... --test_arg=\"--\" --test_arg=\"-l trace\"\n\n# Run tests with IPv4 only\nbazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v4only\n\n# Run tests with IPv6 only\nbazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v6only\n\n# Disable heap checker\nbazel test --config=clang //test/... --test_env=HEAPCHECK=\n```\n\n## Dependencies\n\n### Dependency locations\n\nDepdendencies are configured in `bazel/repository_locations.bzl`, for API deps its `api/bazel/repository_locations.bzl`\n\nSee `bazel/repositories.bzl` for setup - eg this is where any patching is controlled.\n\nIf you need to create or update a patch - do the following:\n\n- checkout the upstream repo at the correct version/commit\n- apply any existing patches\n- make changes\n- diff the changes to the patch file\n\nPay attention to how the patch_args are setup in repositories.bzl - some are p0, while others are p1. Prefer p1 when\ncreating new patches.\n\n\n## Code formatting and linting\n\n### Format code\n\n```bash\n# Check and fix formatting (recommended for source/, test/, contrib/ changes)\nbazel run --config=clang //tools/code_format:check_format -- fix\n\n# Quick format check (much faster, doesn't fix)\nbazel run --config=clang //tools/code:check\n\n# Check format without fixing\nbazel run --config=clang //tools/code_format:check_format -- check\n\n# Format API files\nbazel run --config=clang //tools/proto_format:proto_format -- fix\n```\n\n### Dependency validation\n\n**Always run dependency checks when adding or updating dependencies:**\n\n```bash\n# Validate dependency metadata\nbazel run --config=clang //tools/dependency:validate\n\n# Run dependency tests\nbazel run --config=clang //tools/dependency:validate_test\n\n# Check for dependency setup/updates\n# -v warn: verbosity level, -c release_dates: check release dates, releases: check type\nbazel run --config=clang //tools/dependency:check -- -v warn -c release_dates releases\n```\n\n## Development workflow\n\n### Making changes\n\n1. **Understand the codebase:**\n   - Review [DEVELOPER.md](https://github.com/envoyproxy/envoy/blob/main/DEVELOPER.md) for development guidelines\n   - Check [REPO_LAYOUT.md](https://github.com/envoyproxy/envoy/blob/main/REPO_LAYOUT.md) for repository organization\n   - Read [CONTRIBUTING.md](https://github.com/envoyproxy/envoy/blob/main/CONTRIBUTING.md) for contribution guidelines\n\n2. **Build and test locally:**\n   ```bash\n   # Build Envoy (this is slow/expensive)\n   bazel build --config=clang //source/exe:envoy-static\n\n   # Run relevant tests (often slow/expensive - depending on test)\n   bazel test --config=clang //test/path/to/relevant/tests/...\n\n   # Quick format check\n   bazel run --config=clang //tools/code:check\n   ```\n\n3. **Run Envoy locally:**\n\n   Unless you're testing a build, download a pre-built binary from the [releases page](https://github.com/envoyproxy/envoy/releases):\n\n   ```bash\n   # Download latest release (recommended for testing)\n   wget https://github.com/envoyproxy/envoy/releases/latest/download/envoy-static-linux-x86_64\n   chmod +x envoy-static-linux-x86_64\n   ./envoy-static-linux-x86_64 --config-path /path/to/config.yaml\n\n   # Or after building locally (takes too long, only if needed)\n   ./bazel-bin/source/exe/envoy-static --config-path /path/to/config.yaml\n   ```\n\n## Common development tasks\n\n### Adding or updating dependencies\n\n1. Check [bazel/repository_locations.bzl](https://github.com/envoyproxy/envoy/blob/main/bazel/repository_locations.bzl) for existing dependencies\n2. See [bazel/EXTERNAL_DEPS.md](https://github.com/envoyproxy/envoy/blob/main/bazel/EXTERNAL_DEPS.md) for how to add/update dependencies\n3. **Always run dependency validation after changes:**\n   ```bash\n   # Validate dependency metadata and relationships\n   bazel run --config=clang //tools/dependency:validate\n\n   # Run all dependency checks (recommended)\n   ./ci/do_ci.sh deps\n   ```\n\n## CI and testing\n\n### Using CI scripts vs direct Bazel\n\nThese are the scripts that are run in CI. They also setup the environment and set the\ntoolchain config.\n\nYou will have been provided a `user.bazelrc` that should have startup args matching what\nusing `do_ci.sh` would provide. This ensures dependencies are not re-downloaded.\n\n#### CI script targets\n\n```bash\n# Run all formatting and pre-checks\n./ci/do_ci.sh format\n\n# Run dependency checks (validation + CVE scanning)\n./ci/do_ci.sh deps\n\n# Development build (compile and test)\n./ci/do_ci.sh dev\n\n# Release testing (as done by CI)\n./ci/do_ci.sh release.test_only [OPTIONAL TEST TARGETS]\n\n# Release build\n./ci/do_ci.sh release.server_only\n\n```\n\n#### When to use direct Bazel\n\nUse direct `bazel` commands for:\n- **Targeted builds/tests** - Building or testing specific targets\n- **Iterative development** - Quick rebuilds during active development\n- **Custom configurations** - When you need specific flags not covered by CI scripts\n"}}