Copilot instructions

1# GitHub Copilot instructions for envoyproxy/envoy
2 
3**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).
4 
5## Repository overview
6 
7This repository contains the Envoy proxy, a cloud-native high-performance edge/middle/service proxy. It includes:
8 
9- **source/** - Core C++ implementation of Envoy proxy
10- **test/** - Comprehensive test suite including unit, integration, and performance tests
11- **api/** - Protocol buffer definitions for Envoy's APIs (xDS, filters, etc.)
12- **bazel/** - Bazel build configurations, rules, and toolchain definitions
13- **contrib/** - Community-contributed extensions
14- **mobile/** - Envoy Mobile implementation
15- **tools/** - Development tooling, scripts, and utilities
16- **docs/** - Documentation source files
17 
18## Build system
19 
20This repository uses **Bazel** as its primary build system.
21 
22### Running Bazel commands in Copilot's local environment
23 
24**IMPORTANT:** The key capability for GitHub Copilot is to run Bazel commands directly in the local workspace to build, test, and validate changes.
25**IMPORTANT:** You MUST run `/tmp/fix-bazel-truststore.sh` before the first time you issue a bazel command!!!
26**IMPORTANT:** Many bazel targets will be very slow/expensive to run/build/test - only test with bazel when told to.
27 
28### Bazel configuration files
29 
30- `.bazelrc` - Repository-wide Bazel configuration with build flags and platform settings
31- `user.bazelrc` - Optional user-specific overrides (gitignored)
32- `.bazelversion` - Specifies the exact Bazel version to use
33- `MODULE.bazel` / `WORKSPACE` - Dependency definitions (using bzlmod and WORKSPACE modes)
34 
35### Compiler configuration
36 
37Envoy supports multiple compiler configurations. **Use `--config=clang` by default** unless told otherwise:
38 
39```bash
40# Use Clang with libc++ (recommended, use by default)
41bazel build --config=clang //source/exe:envoy-static
42 
43# Use GCC with libstdc++ (only if explicitly requested)
44bazel build --config=gcc //source/exe:envoy-static
45```
46 
47## Language and coding standards
48 
49### C++
50 
51- **Primary Language:** Modern C++ (C++20)
52- **Compiler Requirements:** Clang >= 18 or GCC >= 13
53- **Standard Library:** libc++ (with Clang) or libstdc++ (with GCC)
54- **Style Guide:** See [STYLE.md](https://github.com/envoyproxy/envoy/blob/main/STYLE.md) for comprehensive coding standards
55 
56## Testing
57 
58### Running tests
59 
60```bash
61# Run all tests
62bazel test --config=clang //test/...
63 
64# Run tests in a specific directory
65bazel test --config=clang //test/common/http/...
66 
67# Run a single test target
68bazel test --config=clang //test/common/http:async_client_impl_test
69 
70# Run tests with additional logging
71bazel test --config=clang --test_output=streamed //test/... --test_arg="--" --test_arg="-l trace"
72 
73# Run tests with IPv4 only
74bazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v4only
75 
76# Run tests with IPv6 only
77bazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v6only
78 
79# Disable heap checker
80bazel test --config=clang //test/... --test_env=HEAPCHECK=
81```
82 
83## Dependencies
84 
85### Dependency locations
86 
87Depdendencies are configured in `bazel/repository_locations.bzl`, for API deps its `api/bazel/repository_locations.bzl`
88 
89See `bazel/repositories.bzl` for setup - eg this is where any patching is controlled.
90 
91If you need to create or update a patch - do the following:
92 
93- checkout the upstream repo at the correct version/commit
94- apply any existing patches
95- make changes
96- diff the changes to the patch file
97 
98Pay attention to how the patch_args are setup in repositories.bzl - some are p0, while others are p1. Prefer p1 when
99creating new patches.
100 
101 
102## Code formatting and linting
103 
104### Format code
105 
106```bash
107# Check and fix formatting (recommended for source/, test/, contrib/ changes)
108bazel run --config=clang //tools/code_format:check_format -- fix
109 
110# Quick format check (much faster, doesn't fix)
111bazel run --config=clang //tools/code:check
112 
113# Check format without fixing
114bazel run --config=clang //tools/code_format:check_format -- check
115 
116# Format API files
117bazel run --config=clang //tools/proto_format:proto_format -- fix
118```
119 
120### Dependency validation
121 
122**Always run dependency checks when adding or updating dependencies:**
123 
124```bash
125# Validate dependency metadata
126bazel run --config=clang //tools/dependency:validate
127 
128# Run dependency tests
129bazel run --config=clang //tools/dependency:validate_test
130 
131# Check for dependency setup/updates
132# -v warn: verbosity level, -c release_dates: check release dates, releases: check type
133bazel run --config=clang //tools/dependency:check -- -v warn -c release_dates releases
134```
135 
136## Development workflow
137 
138### Making changes
139 
1401. **Understand the codebase:**
141   - Review [DEVELOPER.md](https://github.com/envoyproxy/envoy/blob/main/DEVELOPER.md) for development guidelines
142   - Check [REPO_LAYOUT.md](https://github.com/envoyproxy/envoy/blob/main/REPO_LAYOUT.md) for repository organization
143   - Read [CONTRIBUTING.md](https://github.com/envoyproxy/envoy/blob/main/CONTRIBUTING.md) for contribution guidelines
144 
1452. **Build and test locally:**
146```bash
147   # Build Envoy (this is slow/expensive)
148   bazel build --config=clang //source/exe:envoy-static
149 
150   # Run relevant tests (often slow/expensive - depending on test)
151   bazel test --config=clang //test/path/to/relevant/tests/...
152 
153   # Quick format check
154   bazel run --config=clang //tools/code:check
155```
156 
1573. **Run Envoy locally:**
158 
159   Unless you're testing a build, download a pre-built binary from the [releases page](https://github.com/envoyproxy/envoy/releases):
160 
161```bash
162   # Download latest release (recommended for testing)
163   wget https://github.com/envoyproxy/envoy/releases/latest/download/envoy-static-linux-x86_64
164   chmod +x envoy-static-linux-x86_64
165   ./envoy-static-linux-x86_64 --config-path /path/to/config.yaml
166 
167   # Or after building locally (takes too long, only if needed)
168   ./bazel-bin/source/exe/envoy-static --config-path /path/to/config.yaml
169```
170 
171## Common development tasks
172 
173### Adding or updating dependencies
174 
1751. Check [bazel/repository_locations.bzl](https://github.com/envoyproxy/envoy/blob/main/bazel/repository_locations.bzl) for existing dependencies
1762. See [bazel/EXTERNAL_DEPS.md](https://github.com/envoyproxy/envoy/blob/main/bazel/EXTERNAL_DEPS.md) for how to add/update dependencies
1773. **Always run dependency validation after changes:**
178```bash
179   # Validate dependency metadata and relationships
180   bazel run --config=clang //tools/dependency:validate
181 
182   # Run all dependency checks (recommended)
183   ./ci/do_ci.sh deps
184```
185 
186## CI and testing
187 
188### Using CI scripts vs direct Bazel
189 
190These are the scripts that are run in CI. They also setup the environment and set the
191toolchain config.
192 
193You will have been provided a `user.bazelrc` that should have startup args matching what
194using `do_ci.sh` would provide. This ensures dependencies are not re-downloaded.
195 
196#### CI script targets
197 
198```bash
199# Run all formatting and pre-checks
200./ci/do_ci.sh format
201 
202# Run dependency checks (validation + CVE scanning)
203./ci/do_ci.sh deps
204 
205# Development build (compile and test)
206./ci/do_ci.sh dev
207 
208# Release testing (as done by CI)
209./ci/do_ci.sh release.test_only [OPTIONAL TEST TARGETS]
210 
211# Release build
212./ci/do_ci.sh release.server_only
213 
214```
215 
216#### When to use direct Bazel
217 
218Use direct `bazel` commands for:
219- **Targeted builds/tests** - Building or testing specific targets
220- **Iterative development** - Quick rebuilds during active development
221- **Custom configurations** - When you need specific flags not covered by CI scripts
222