Service mappings
Tell the AI which service in your logs corresponds to which path inside which connected repository
A service mapping tells SigSentry that when a log line says
service=checkout-api, the corresponding source code lives at
acme/checkout-api (or in a subdirectory of a monorepo). Without
mappings, the AI guesses; with them, code correlation becomes
deterministic.
Why mappings matter
Imagine you have:
| Log says... | And the code is... |
|---|---|
service=checkout-api | acme/checkout-api (its own repo) |
service=billing-worker | acme/payments at path services/billing-worker/ |
service=user-api | acme/payments at path services/user-api/ |
Without mappings, the AI sees service=billing-worker and tries to
find a repo called billing-worker. There isn't one. With mappings,
it knows to read acme/payments at services/billing-worker/.
Configuring mappings
In Project → Code Repos, edit a repo connection. Each row of the service mappings table has:
| Field | What it means |
|---|---|
| Service name | The exact value of the service field in your logs |
| Repository | Which connected repo this service lives in (owner/repo format) |
| Path prefix | Optional — for monorepos, the directory inside the repo. Empty means root |
| Default branch | What branch to read from. Default main |
You can have multiple mappings per repo. The AI matches the service
name against your logs' service field exactly (case-sensitive).
Examples
Polyrepo: one repo per service
| Service | Repo | Path | Branch |
|---|---|---|---|
checkout-api | acme/checkout-api | (empty) | main |
billing-worker | acme/billing-worker | (empty) | main |
user-api | acme/user-api | (empty) | main |
Monorepo: services share a repo
| Service | Repo | Path | Branch |
|---|---|---|---|
checkout-api | acme/services | apps/checkout-api/ | main |
billing-worker | acme/services | apps/billing-worker/ | main |
user-api | acme/services | apps/user-api/ | main |
Mixed: some services in monorepo, some standalone
| Service | Repo | Path | Branch |
|---|---|---|---|
frontend | acme/web | (empty) | main |
checkout-api | acme/services | apps/checkout-api/ | main |
legacy-api | acme/legacy-api | (empty) | master |
What if I don't configure mappings?
Without mappings, the AI falls back to a heuristic — it'll try to match the service name to a repo name. This works for polyrepos with matching names, but breaks for monorepos and any service whose log field doesn't match a repo.
A common symptom of missing mappings is the unresolved services banner on an analysis result, telling you that the AI couldn't find source code for one or more services. Add mappings to resolve.
Branches and refs
By default, mappings read from the configured default branch
(usually main). The AI can also read from a specific commit SHA when
a stack trace or PR mentions one — for example, if the analysis
window includes a deploy at abc1234, the AI may read files at that
specific SHA to match the running code at the time of the incident.
Updating mappings
Service mappings are stored as part of the repo configuration. Edit them anytime under Project → Code Repos → Edit. Changes take effect on the next analysis.
When the heuristic is good enough
If your service names match repo names one-to-one, you can skip mappings entirely. The AI's fallback heuristic handles this case well. Mappings become essential as soon as you have any of:
- A monorepo with multiple services
- Service names in logs that differ from repo names
- Multiple services that should share code review history
- Services whose code lives on a non-default branch