envoy (Agent Skills)

# AGENTS.md

Instructions for AI coding agents (Claude Code, Copilot, Cursor, etc.) working in this repository.

## Critical rules

1. **Always sign off commits.** The human user must sign off commits via `git commit -s` — never
   manually write a `Signed-off-by` trailer. The sign-off attests that the committer (the user)
   has the right to submit the code under the project's license.
2. **Always run format and lint checks before committing.** Use `tools/local_fix_format.sh` for
   a quick local check, or run `./ci/do_ci.sh format` inside Docker for the full CI check suite.
   Format failures are the most common CI rejection. If running checks is impractical, warn the
   user that formatting has not been verified.
3. **Never amend commits or force-push after a PR has received human review.** Always create new
   commits to preserve review history.
4. **Never rebase a PR that is under review.** Use `git merge main` instead to pull in recent
   changes. The project squash-merges, so commit count does not matter.
5. **Disclose AI usage.** When submitting PRs, include a note about AI assistance in the PR
   description. The submitter must fully understand all code being submitted.
6. **Never commit to `main`.** Always create a new branch before committing. If switching
   contexts or unsure which branch to use, ask the user.
7. **Always push to a personal fork.** Do not create branches in the main repo.

## Developer workflow

### 1. Before starting work

Read `CONTRIBUTING.md` for the full contribution process. Key points:
- **Major features (>100 LOC or user-facing):** Open a GitHub issue first to discuss design.
  For new extensions, read `EXTENSION_POLICY.md`.
- **Small patches and bug fixes:** No prior communication needed.
- Install git hooks: `./support/bootstrap`

### 2. Writing code

Read `STYLE.md` for the C++ coding style. After writing C++ code, run `clang-format` to fix
formatting automatically rather than trying to hand-format:

```bash
clang-format -i <file>
```

Tests must:
- Live in `test/` mirroring the `source/` structure
- Achieve 100% coverage for new code
- Use `StrictMock` by default, `SimulatedTimeSystem` for time, port 0 for network
- Unit tests must be hermetic and deterministic — no real time, no randomness
- Integration tests (in `test/integration/`) use real network on localhost

### 3. Building and testing

See `bazel/README.md` for full build documentation. Common commands:

```bash
# Docker-based (recommended — matches CI environment)
./ci/run_envoy_docker.sh bash                                   # interactive shell
./ci/do_ci.sh debug //test/common/http/...                      # build + test
./ci/do_ci.sh debug.server_only                                 # build binary only

# Local (requires local dependencies)
bazel test -c dbg //test/common/http/...                         # run tests
bazel build --config=clang -c opt //source/exe:envoy-static      # optimized binary
```

Sanitizers, coverage, GDB debugging, and profiling are resource-intensive. Do **not** run
them unless the user explicitly asks. See `bazel/README.md` and `bazel/PPROF.md`.

### 4. Format and lint checks (required before every commit)

Format failures are the most common CI rejection. Agents should produce content that conforms
to the repo's style conventions for all file types (C++, BUILD, YAML, Markdown, shell, etc.).

**Quick local check (recommended):**

```bash
tools/local_fix_format.sh          # uncommitted changes (default)
tools/local_fix_format.sh -main    # changes since main
tools/local_fix_format.sh -all     # entire repo
```

**Individual checks:**

```bash
bazel run //tools/code_format:check_format -- fix      # C++, BUILD, .bzl, .proto
bazel run //tools/spelling:check_spelling_pedantic -- fix   # spelling
./ci/do_ci.sh format                                   # full CI check (inside Docker)
```

**Linter config files — read these to produce compliant output without running the tools:**

| Config file | What it configures |
|-------------|--------------------|
| `.clang-format` | C++/Proto formatting (100-col, include order, pointer alignment) |
| `.yamllint` | YAML rules (140-col max, consistent indentation) |
| `.flake8` | Python lint rules |
| `rustfmt.toml` | Rust formatting (100-col, 2-space indent) |
| `tools/spelling/spelling_dictionary.txt` | Custom word list (1700+ project terms) |

### 5. Creating the commit

Before your first commit in a session:

1. Check if the local `main` is up to date with `origin/main`:
   ```bash
   git fetch origin
   git log main..origin/main --oneline
   ```
2. If `main` is behind, sync it:
   ```bash
   git checkout main && git pull && git checkout -
   ```
3. Create a new branch off the updated `main`:
   ```bash
   git checkout -b <descriptive-branch-name>
   ```
4. If you had uncommitted changes that conflict with the updated `main`, ask the user whether
   to proceed on the outdated base or resolve conflicts against the new `main`.

If you're switching contexts or unsure which branch to commit to, ask the user before committing.

```bash
git add <files>
git commit -s    # -s adds Signed-off-by automatically; NEVER write it manually
```

### 6. Pushing and creating a PR

**PR title format** — lower-case subsystem prefix followed by a colon:
`docs: fix grammar error`, `router: add x-envoy-overloaded header`

**PR description template** — every PR must fill in:

```
Commit Message: <what this PR does — used as the final squash-merge message>
Additional Description: <context useful to reviewers>
Risk Level: Low | Medium | High
Testing: <what testing was done>
Docs Changes: <description or N/A>
Release Notes: <description or N/A>
```

See `PULL_REQUESTS.md` for full field descriptions and optional fields (runtime guard,
deprecation, platform-specific features).

**Release notes:** User-facing changes **must** add a release note fragment under
`changelogs/current/`. Name the file `<area>__<short-description>.rst`.

### 7. Waiting for CI and review

- Do **not** create draft PRs if you want prompt reviews — draft PRs are not triaged.
- To re-run failed CI tasks, add a `/retest` comment on the PR.
- PRs with no activity for 14+ days may be closed.

### 8. Addressing review comments

- **Never amend or force-push** after a reviewer has looked at the PR. Create new commits.
- **Never rebase.** If you need to incorporate upstream changes:
  ```bash
  git fetch origin main && git merge origin/main
  ```
- If the reviewer asked for a runtime guard, add one (see `CONTRIBUTING.md`).

### 9. After merge

The project squash-merges PRs. The "Commit Message" field in your PR description becomes the
final commit message. Make sure it's up to date before merge.

## Understanding CI

Envoy uses a checks-based CI system. Results appear as **GitHub Check Runs** on PRs, not as
simple workflow pass/fail statuses.

**CI pipeline:**

1. **`Envoy/Prechecks`** — fast checks: format/lint/spelling, dependency validation, docs build
2. **`Envoy/Checks`** — heavier checks: compilation, tests, coverage, sanitizers

**Checking CI status:**

```bash
gh pr checks <PR-number>
gh run view <run-id> --log-failed
```

When CI fails, check the failed check run name to determine which `do_ci.sh` target to
reproduce locally. Format failures come from `Envoy/Prechecks`; build/test failures come
from `Envoy/Checks`.

## Inclusive language

The following terms are **not allowed**:
- ~~whitelist~~ -> allowlist
- ~~blacklist~~ -> denylist / blocklist
- ~~master~~ -> primary / main
- ~~slave~~ -> secondary / replica

## BUILD file conventions

See `bazel/DEVELOPER.md` for full BUILD file rules. Key points:
- Use `envoy_cc_library`, `envoy_cc_test`, `envoy_cc_mock` (not raw `cc_library`)
- Target suffixes: `_lib`, `_test`, `_mocks`, `_interface`
- Every `#include` must have a corresponding `deps` entry

## Updating dependencies

See `bazel/EXTERNAL_DEPS.md` and `DEPENDENCY_POLICY.md`. When updating a version:
1. Update version, sha256, and urls in `bazel/repository_locations.bzl`
2. Update `release_date` in `bazel/deps.yaml` to the UTC date of the new release
3. Prefer maintainer-provided tarballs over GitHub auto-generated ones

## CI and GitHub Actions (for workflow file authors)

- In `if:` conditions, do **not** wrap expressions in `${{ }}` — the `if` field evaluates
  expressions implicitly. Use `${{ }}` only in string contexts (`run:`, `with:`, `env:`).
- Workflow files in `.github/workflows/` are shared across all branches (main and stable release
  branches). Do not remove variables or inputs still referenced by stable branches.

## Key files

| File | Purpose |
|------|---------|
| `STYLE.md` | C++ coding style and error handling |
| `CONTRIBUTING.md` | Contribution guidelines, deprecation, breaking changes |
| `PULL_REQUESTS.md` | PR field descriptions |
| `EXTENSION_POLICY.md` | Extension lifecycle and requirements |
| `DEPENDENCY_POLICY.md` | External dependency rules |
| `RELEASES.md` | Release schedule and backport process |
| `SECURITY.md` | Security reporting and disclosure |
| `REPO_LAYOUT.md` | Repository structure |
| `bazel/README.md` | Building, testing, sanitizers, coverage |
| `bazel/DEVELOPER.md` | BUILD file conventions |
| `bazel/EXTERNAL_DEPS.md` | Managing external dependencies |
| `bazel/PPROF.md` | Performance profiling |
| `source/extensions/extensions_metadata.yaml` | Extension status and security posture |
| `source/common/runtime/runtime_features.cc` | Runtime feature flag defaults |

# GitHub Copilot instructions for envoyproxy/envoy

**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).

## Repository overview

This repository contains the Envoy proxy, a cloud-native high-performance edge/middle/service proxy. It includes:

- **source/** - Core C++ implementation of Envoy proxy
- **test/** - Comprehensive test suite including unit, integration, and performance tests
- **api/** - Protocol buffer definitions for Envoy's APIs (xDS, filters, etc.)
- **bazel/** - Bazel build configurations, rules, and toolchain definitions
- **contrib/** - Community-contributed extensions
- **mobile/** - Envoy Mobile implementation
- **tools/** - Development tooling, scripts, and utilities
- **docs/** - Documentation source files

## Build system

This repository uses **Bazel** as its primary build system.

### Running Bazel commands in Copilot's local environment

**IMPORTANT:** The key capability for GitHub Copilot is to run Bazel commands directly in the local workspace to build, test, and validate changes.
**IMPORTANT:** You MUST run `/tmp/fix-bazel-truststore.sh` before the first time you issue a bazel command!!!
**IMPORTANT:** Many bazel targets will be very slow/expensive to run/build/test - only test with bazel when told to.

### Bazel configuration files

- `.bazelrc` - Repository-wide Bazel configuration with build flags and platform settings
- `user.bazelrc` - Optional user-specific overrides (gitignored)
- `.bazelversion` - Specifies the exact Bazel version to use
- `MODULE.bazel` / `WORKSPACE` - Dependency definitions (using bzlmod and WORKSPACE modes)

### Compiler configuration

Envoy supports multiple compiler configurations. **Use `--config=clang` by default** unless told otherwise:

```bash
# Use Clang with libc++ (recommended, use by default)
bazel build --config=clang //source/exe:envoy-static

# Use GCC with libstdc++ (only if explicitly requested)
bazel build --config=gcc //source/exe:envoy-static
```

## Language and coding standards

### C++

- **Primary Language:** Modern C++ (C++20)
- **Compiler Requirements:** Clang >= 18 or GCC >= 13
- **Standard Library:** libc++ (with Clang) or libstdc++ (with GCC)
- **Style Guide:** See [STYLE.md](https://github.com/envoyproxy/envoy/blob/main/STYLE.md) for comprehensive coding standards

## Testing

### Running tests

```bash
# Run all tests
bazel test --config=clang //test/...

# Run tests in a specific directory
bazel test --config=clang //test/common/http/...

# Run a single test target
bazel test --config=clang //test/common/http:async_client_impl_test

# Run tests with additional logging
bazel test --config=clang --test_output=streamed //test/... --test_arg="--" --test_arg="-l trace"

# Run tests with IPv4 only
bazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v4only

# Run tests with IPv6 only
bazel test --config=clang //test/... --test_env=ENVOY_IP_TEST_VERSIONS=v6only

# Disable heap checker
bazel test --config=clang //test/... --test_env=HEAPCHECK=
```

## Dependencies

### Dependency locations

Depdendencies are configured in `bazel/repository_locations.bzl`, for API deps its `api/bazel/repository_locations.bzl`

See `bazel/repositories.bzl` for setup - eg this is where any patching is controlled.

If you need to create or update a patch - do the following:

- checkout the upstream repo at the correct version/commit
- apply any existing patches
- make changes
- diff the changes to the patch file

Pay attention to how the patch_args are setup in repositories.bzl - some are p0, while others are p1. Prefer p1 when
creating new patches.


## Code formatting and linting

### Format code

```bash
# Check and fix formatting (recommended for source/, test/, contrib/ changes)
bazel run --config=clang //tools/code_format:check_format -- fix

# Quick format check (much faster, doesn't fix)
bazel run --config=clang //tools/code:check

# Check format without fixing
bazel run --config=clang //tools/code_format:check_format -- check

# Format API files
bazel run --config=clang //tools/proto_format:proto_format -- fix
```

### Dependency validation

**Always run dependency checks when adding or updating dependencies:**

```bash
# Validate dependency metadata
bazel run --config=clang //tools/dependency:validate

# Run dependency tests
bazel run --config=clang //tools/dependency:validate_test

# Check for dependency setup/updates
# -v warn: verbosity level, -c release_dates: check release dates, releases: check type
bazel run --config=clang //tools/dependency:check -- -v warn -c release_dates releases
```

## Development workflow

### Making changes

1. **Understand the codebase:**
   - Review [DEVELOPER.md](https://github.com/envoyproxy/envoy/blob/main/DEVELOPER.md) for development guidelines
   - Check [REPO_LAYOUT.md](https://github.com/envoyproxy/envoy/blob/main/REPO_LAYOUT.md) for repository organization
   - Read [CONTRIBUTING.md](https://github.com/envoyproxy/envoy/blob/main/CONTRIBUTING.md) for contribution guidelines

2. **Build and test locally:**
   ```bash
   # Build Envoy (this is slow/expensive)
   bazel build --config=clang //source/exe:envoy-static

   # Run relevant tests (often slow/expensive - depending on test)
   bazel test --config=clang //test/path/to/relevant/tests/...

   # Quick format check
   bazel run --config=clang //tools/code:check
   ```

3. **Run Envoy locally:**

   Unless you're testing a build, download a pre-built binary from the [releases page](https://github.com/envoyproxy/envoy/releases):

   ```bash
   # Download latest release (recommended for testing)
   wget https://github.com/envoyproxy/envoy/releases/latest/download/envoy-static-linux-x86_64
   chmod +x envoy-static-linux-x86_64
   ./envoy-static-linux-x86_64 --config-path /path/to/config.yaml

   # Or after building locally (takes too long, only if needed)
   ./bazel-bin/source/exe/envoy-static --config-path /path/to/config.yaml
   ```

## Common development tasks

### Adding or updating dependencies

1. Check [bazel/repository_locations.bzl](https://github.com/envoyproxy/envoy/blob/main/bazel/repository_locations.bzl) for existing dependencies
2. See [bazel/EXTERNAL_DEPS.md](https://github.com/envoyproxy/envoy/blob/main/bazel/EXTERNAL_DEPS.md) for how to add/update dependencies
3. **Always run dependency validation after changes:**
   ```bash
   # Validate dependency metadata and relationships
   bazel run --config=clang //tools/dependency:validate

   # Run all dependency checks (recommended)
   ./ci/do_ci.sh deps
   ```

## CI and testing

### Using CI scripts vs direct Bazel

These are the scripts that are run in CI. They also setup the environment and set the
toolchain config.

You will have been provided a `user.bazelrc` that should have startup args matching what
using `do_ci.sh` would provide. This ensures dependencies are not re-downloaded.

#### CI script targets

```bash
# Run all formatting and pre-checks
./ci/do_ci.sh format

# Run dependency checks (validation + CVE scanning)
./ci/do_ci.sh deps

# Development build (compile and test)
./ci/do_ci.sh dev

# Release testing (as done by CI)
./ci/do_ci.sh release.test_only [OPTIONAL TEST TARGETS]

# Release build
./ci/do_ci.sh release.server_only

```

#### When to use direct Bazel

Use direct `bazel` commands for:
- **Targeted builds/tests** - Building or testing specific targets
- **Iterative development** - Quick rebuilds during active development
- **Custom configurations** - When you need specific flags not covered by CI scripts