Make Targets

Every workflow in Esmeralda runs through the root Makefile. Run make help for the same list in your terminal. Most targets take ENV=<env> (default dev).

Note

This page is generated from the ## ... comments in the Makefile at build time.

Setup, local development and tests

Target	What it does
make help	Show this help message
make preflight	Run preflight checklist to validate active GCP project, credentials, and billing status
make hooks	Install the git hooks (.githooks: pre-commit sensitive scan, pre-push uv.lock check)
make bootstrap	Setup local python virtual environments and sync workspace dependencies via uv
make test-agents	Fast execution for agent unit tests only
make test-terraform	Run syntax validation for all Terraform modules (+ workload image digest pinning check)
make test-gateway-unit	Envoy gateway harness (offline): renders the config module and runs it in a real envoy (needs envoy + terraform/tofu)
make test-guards	Run repository hygiene, manifest parity, governance capability contract and security policy guards
make test-apigee	Offline unit and policy conformance tests for Apigee capability bundles and modules
make test-all	Run the uv.lock check, Python unit tests, repo guards, Terraform validation, Envoy gateway harness, and Apigee policy tests
make lock	Regenerate uv.lock against public PyPI (in Cloud Build) from your working copy; PKG="a b==1.2" also upgrades those
make lock-check	Fail if uv.lock is out of date with the pyproject.toml files (offline; also the git pre-push hook)
make test	Run unit tests across all workspace members
make test-release	Unit tests for the release manifest writer (scripts/release_manifest.py, stdlib only)
make run-mcp-local	Launch the 3 MCP servers locally on dedicated localhost ports

Query any agent (ADK or A2A) the same way: in-process, on a running server, or deployed

Target	What it does
make query	Query an agent: AGENT= [QUERY="..."] [TARGET=local|remote|] (remote = the ENV deployment)
make serve	Serve an agent locally exactly as in the container: AGENT= [PORT=8080] [WEB=1 for the ADK dev UI]

End-to-end tests of a deployed environment (engine IDs from Terragrunt outputs)

Target	What it does
make test-e2e	End-to-end check of a deployed env: specialist, then orchestrator -> specialist (fails on any error)

Layer 0: shared CI/CD (env-independent; one project, dev + release repositories)

Target	What it does
make deploy-cicd	Deploy Layer 0: shared CI/CD project, dev + release Artifact Registry repos, builder/promoter SAs

Layers 1-3: foundations (projects, networking, security + internal PKI)

Target	What it does
make deploy-projects	Deploy Layer 1: Projects via Terragrunt for $(ENV)
make deploy-networking	Deploy Layer 2: Networking via Terragrunt for $(ENV)
make deploy-security	Deploy Layer 3: Security + internal Root CA via Terragrunt for $(ENV)
make deploy-foundations	Deploy Layers 1-3 (Projects, Networking, Security)

Layer 4: governance (Agent Gateway + ACT + IAP, Agent Registry, Model Armor, telemetry)

Target	What it does
make deploy-governance	Deploy Layer 4: Governance, Agent Gateway, Observability & Alerts for $(ENV)

Image builds: env-neutral, always pushed to the shared dev repository

Target	What it does
make build-ai-coe-mortgage-specialist	Build and push the AI CoE mortgage specialist (A2A) image
make build-cx-mortgage-orchestrator	Build and push the CX mortgage orchestrator image
make build-agents	Run tests (not the gateway harness: no envoy needed), then build both agent images concurrently (SKIP_TESTS=1 if you just ran them)
make build-service-income-verification	Build and push the Income Verification MCP image
make build-service-corporate-email	Build and push the Corporate Email MCP image
make build-service-legacy-dms	Build and push the Legacy DMS MCP image
make build-service-envoy	Build and push the Envoy gateway image (digest-pinned upstream Envoy, no custom code)
make build-services	Build all MCP service + Envoy gateway images concurrently
make build-images	Build every image deployed by Layer 5

Layer 5: workloads (MCP services -> agents -> gateways -> entry point -> IAP egress), Terragrunt DAG

Target	What it does
make deploy-workloads	Deploy Layer 5 in dependency order (MCP services, agents, gateways, entry point, IAP egress, test VM)
make verify-images	Check every Layer 5 workload runs the expected digest: release/.yaml if present, else its tag
make deploy-services	Deploy the 3 MCP services on Cloud Run (+ their Agent Registry entries)
make deploy-ai-coe-mortgage-specialist	Deploy the AI CoE mortgage specialist (A2A) Reasoning Engine
make deploy-cx-mortgage-orchestrator	Deploy the CX mortgage orchestrator Reasoning Engine
make deploy-agents	Deploy both Reasoning Engine agents, in parallel (no deploy-time dependency between them)
make deploy-gateway	Deploy the built-in direct backends (gateways/direct; re-run after agents are recreated: routes use engine IDs)
make deploy-entrypoint	Deploy the internal entry point (URL map, HTTPS proxy, forwarding rule) after the gateways
make test-gateway	Probe every catalog host through the entry point from the test VM (IAP SSH), incl. a real orchestrator query: ENV=
make test-partner	Run partner front-door conformance checks (401 unauth, 403/404 agent/MCP scope, SSE TTFB + answer, 429 quota): ENV=
make deploy-iap-egress	Grant roles/iap.egressor on every Agent Registry entry (final Layer 5 step)

Operations CLI (delegates to uv run esmeralda ...)

Target	What it does
make status	Show git branch/SHA, active worktrees, local state units, image tags/digests, and deployed outputs: ENV=
make doctor	Workstation preflight check (tools, billing env var, ADC token, uv.lock, local states): ENV=
make units	List Terragrunt units, layer, dependencies, enabled/excluded status, and local state presence: ENV=
make plan	Run read-only terragrunt plan on a unit (or --all) and print a compact summary: [UNIT=] ENV=
make apply	Plan a unit to a planfile, enforce the destroy guard, and apply the saved planfile: UNIT= ENV= [ALLOW_DESTROY=1]
make verify	Run gateway conformance probes and remote specialist + orchestrator queries: ENV=
make logs	Fetch recent Cloud Logging entries for an agent or MCP service: TARGET_NAME= ENV=
make guard	Scan all tracked files in the repository for secrets and forbidden internal strings
make build-package	Build the PyPI wheel and sdist (esmeralda-platform) into dist/ and verify contents

Whole environment

Target	What it does
make deploy-all	Build an env from zero: Layer 0 -> 1-3 -> 4 -> images -> 5 (single pass)
make destroy-all	Destroy an env's Layers 5 -> 1 (dev only; never touches the shared Layer 0)

Releases: copy dev images by digest into the immutable release repository

Target	What it does
make status-release	Show the prd release manifest (version, source, digests) and the shared repositories
make promote	Promote a verified dev build by digest + write release/prd.yaml: VERSION=vX.Y.Z SOURCE=dev- VERIFIED=YYYY-MM-DD; no deploy
make test-governance-chaos	Run local chaos simulation test for governance telemetry and alerts
make load-test	Locust load test of a deployed ADK agent: [LOAD_AGENT=cx-mortgage-orchestrator] [USERS=5] [DURATION=1m] ENV=dev (results in tests/load_test/.results)
make load-test-partner	Locust load test THROUGH the Apigee partner front door, run from the test VM: [USERS=2] [DURATION=5m] [INCLUDE_QUOTA=1] ENV=dev (results in tests/load_test/.results/partner)

Documentation site (MkDocs Material, published to GitHub Pages by .github/workflows/docs.yml)

Target	What it does
make docs-serve	Preview the documentation site locally on http://127.0.0.1:8000 (live reload)
make docs-build	Build the documentation site into site/ in strict mode (fails on broken links)
make clean	Clean python virtual environments, caches, and terragrunt cache files recursively