Map and discovery
Discovery reads every connection in your workspace and builds one map: what you run, where it runs, and how the pieces depend on each other. Every later step, from deploys to incident investigations, starts from this map.
Running discovery
On the Connections page, choose Run discovery to read every connection at once, or Refresh on one connection to read only that one. Owners and approvers can start discovery; viewers see the results.
Discovery is a run like any other, so you can watch it live under Runs: one step per connection, then Scout's summary, then a result line with what changed. A connection that fails is marked with the reason on the Connections page, and the others still finish. Run discovery again after you fix it.
Discovery only reads. On AWS it uses the read-only role, on GitHub short-lived installation tokens, on Vercel your token through read endpoints, and on Kubernetes your service account with get, list, and watch.
What each connection reads
AWS
A Resource Explorer search in each of the connection's regions finds what exists, then read calls fill in the configuration: ECS clusters and services with their task definitions, ECR repositories, RDS databases and Aurora clusters, Lambda functions, load balancers, EC2 instances, VPCs and security groups, IAM roles, log groups, and Secrets Manager secrets (name, tags, and when they changed, never the value). SQS queues, SNS topics, DynamoDB tables, ElastiCache clusters, API Gateway APIs, CloudFront distributions, and EventBridge rules appear on the map too.
GitHub
For each linked repository: its metadata, recent commits, workflows and recent workflow runs. Groundcrew also takes a shallow copy of the repository, reads what it says about your system, and deletes the copy:
- Terraform resources and what each one references.
- GitHub Actions workflows: triggers, roles they assume, images they push, ECS and Vercel deploy steps.
- Dockerfiles, compose files, and the names of env vars the code reads.
Only names and structure are kept. .env files are skipped, and nothing in your repository is run during discovery.
Vercel
Projects and the repository each one is linked to, production domains, recent production deployments, and env var names and types. Connect Vercel lists the one kind of value that is kept.
Kubernetes
Namespaces, Deployments, StatefulSets, Services, and Ingresses. Pods, events, and pod logs are read when an incident is checked or investigated. Secrets and ConfigMaps are not listed.
How resources are linked
After every discovery Groundcrew works out the lines between resources from what it read. Each line has a kind and keeps the evidence it came from, so you can see why two things are connected.
| Line | Means | Example |
|---|---|---|
| calls | Sends requests to | A Vercel frontend calls an API on ECS |
| reads | Reads data from | A service reads an RDS database |
| uses | Gets a secret or config from | A task definition uses a secret |
| pulls from | Pulls its image from | A service pulls from an ECR repository |
| logs to | Sends its logs to | A service logs to a CloudWatch log group |
| deployed by | Is deployed by | A service is deployed by a GitHub workflow |
| defined in | Is defined in | A database is defined in a Terraform file |
Lines across providers are the point of the map. When an incident starts on a service, Medic follows these lines to the database it reads, the secret it uses, the log group it writes to, and the commit that deployed it.
Coverage
Every resource has one of three coverage levels, shown on its details panel:
- Observed: Groundcrew knows it exists and how it is configured.
- Diagnosable: Groundcrew can also read its logs or metrics, so Medic can investigate it. A service usually becomes diagnosable through its logs to line.
- Actionable: a deploy target or an emergency fix can change it, after an approval.
Reading the map
The map groups resources by provider. Use Providers and Show above the map to filter what you see. Select a resource to open its panel: its type, region, tags, configuration, coverage, and every line to and from it, with the evidence for each.
At the top, Scout's summary describes the system in a few sentences: what the main apps are, what they depend on, and what looks unusual. It is rewritten after each discovery.
AWS regions
Each AWS connection has a list of regions Groundcrew discovers, watches for incidents, and acts in. An owner changes it with Regions on the connection, up to 10 regions. The roles are global, so no stack update is needed; Groundcrew refreshes the map after you save.
The Resource Explorer index the template creates covers the region you created the stack in. In a region without an index, Groundcrew finds resources through the AWS tagging API instead and says so in the discovery run.
Stale and missing resources
A resource that the latest complete discovery of its connection did not see is marked stale: it stays in the workspace, is hidden from the map by default, and its panel says "Not seen in the last discovery". To see them, tick Not seen in the last discovery under Show. Lines are worked out again on every discovery from the resources that are not stale.
If something you expect is missing:
- Check it is in one of the connection's regions.
- For a repository, check it is linked on the GitHub connection, not only shared with the app on GitHub.
- For Kubernetes, check the service account can list that kind in that namespace.
- Look at the discovery run's steps under Runs. Each connection's step lists notes about what it could not read.
Limits
Discovery keeps up to 2,000 resources per connection, and says so in the run when it found more. Each connection has about 100 seconds; one that takes longer is marked as failed with the reason, and the others still finish. A workspace can have up to 10 connections. All limits.