Service catalog

Overview

The catalog answers the four questions nobody can answer from a repository list: what do we run, who owns it, where is it deployed, and is it any good? A service is a named unit of software mapped onto a set of repository paths, so one repository can hold five services and one service can span three repositories. Ownership is a real group — the one a failing check files work into, and the one that stands in as code owner wherever a repository requires code-owner review and no CODEOWNERS rule matches the path — so setting it does something rather than describing something.

You do not start from an empty page. Every repository already appears as a service, created with the repository itself, so your first job is splitting and correcting rather than filling in a form.

Quick start

Before you start

How it works

A service is an overlay, not a repository

A service binds to a set of (repository, path glob) pairs. That single decision is what makes a monorepo native instead of an apology.

Four things fall out of the binding and each would otherwise be its own feature: per-service ownership, per-service technical debt, pipeline nodes that run only when their own folder changed, and a deploy that knows which of five services it deployed.

When two globs match one path, the winner is decided in a fixed order — longest literal prefix first, then the glob with fewer wildcards, then a stable tie-break. An exclude glob removes its own matches before any of that, so paths: ["services/checkout/**"] with exclude: ["**/vendor/**"] does what it reads like. The order is fixed rather than resolved by row order because a service's owner can gate a merge, and a gate that flips depending on which row was read first is not a gate.

Identity, address and where an entry came from

A service's id never changes. The slug is the address, it changes, and it is unique across your whole organisation rather than per group — a depends_on: entry in another repository's catalog file, a pipeline node's service: and the by-slug lookup all need payments-api to resolve without a path in front of it. The cost is real: at a couple of hundred services you will occasionally have to call something payments-api-v2.

Every entry records how it came to exist, and that is visible on purpose:

A human has vouched for this is simply source not being inferred, which is a scorecard check you can turn on rather than a banner nobody dismisses.

A declaration is a refinement, and it never destroys history

.gitmoap/catalog.yaml — or the same path with a .yml extension, either works — on the default branch splits and corrects the catalog. An entry needs only a slug. kind defaults to service, lifecycle to production, display_name to the slug, and paths to ** when the file declares exactly one service — declare two and every entry must name its own paths. owner may be left out too, and the entry is then unowned, which is exactly what the has an owner check exists to surface, so name a team while you are there:

Exactly one of the two extensions may exist in a repository; both at once is a validation error naming them. The file is validated on every branch and applied only on the default one, and the result is posted as a gitmoap/catalog commit status — so a broken declaration is a red check inside the merge request, seen by the person who caused it, before it lands. A file with any error applies none of its services.

A file of forty near-identical entries repeats itself, and a defaults: block above services: is the remedy — kind, lifecycle, owner, exclude and annotations set there apply to every entry that does not state its own. It is the reuse mechanism on purpose: YAML anchors would not survive a change of format, and this one round-trips.

The first catalog file in a repository does not throw away what the catalog already knew. If exactly one declared service covers the whole repository — paths: ["**"], or no paths at all — it adopts the entry created with the repository: same id, same deployments, same check history, now marked as declared. Declare two or more, or narrow the paths, and you are splitting: the declared services are new entries and the original is orphaned rather than deleted, so its history stays readable while you decide what to do with it.

When a declaration disappears the service is orphaned, never deleted: nothing attached to it is touched. Most disappearances are a bad merge or a refactor in flight, and reaping a deploy history over one would destroy the record rather than tidy it. Bring the declaration back and the same service is revived, with its id, its deployments and its check history intact. Deleting is an explicit act by somebody who can see what they are destroying.

Environments are one row, resolved by a walk up the tree

An environment is a named place software runs, carrying the policy that governs deploying to it. It is exactly one row, owned by exactly one scope. Declaring production on your root group does not copy it into 400 repositories — it makes one row that every descendant may reference.

A nearer slug shadows a farther one, so a repository can have its own staging without disturbing the organisation's. slug is whatever you call it — prod, live, eu-west-1-blue — while tier is one of development, testing, staging or production, and the tier is what lets a check say deployed to production within 30 days without knowing your naming.

A production-tier environment is gated by default. Create one with no protection block and you get approval required, the people given access on the owning group named as its approvers, and deploys restricted to one branch — the repository's own default branch when you declare it on a repository, and main when you declare it on a group, since a group has no default branch to inherit. Turning any of that off is a deliberate edit, because a feature whose safe configuration requires reading the documentation is unsafe in the median case.

allowed_scopes is the other half, and it is an access rule rather than an approval rule: leave it unset and the declaring scope's subtree may use the environment; set it and only the groups and repositories you name may. Protection gates approval; this gates reach.

Deployments are recorded, never entered

Every deployment is an edge from a pipeline run to a (service, environment) at a commit, written by the platform when a node that named both starts and finishes.

Two consequences worth knowing. A rollback is a new deployment, not a status change on the old one — redeploying v2.13.0 over v2.14.0 writes a fresh row and marks the previous one superseded, so the history and the current pointer never disagree about what was true at 14:00. And a deployment outlives its run: reaping pipeline history does not erase the record of what went to production.

Checks come in three kinds

Each result is one of six states, and three of them exist to stop a scorecard lying. not_applicable leaves the denominator entirely — a library has no deployments, so marking it red teaches people to ignore red. unknown means never evaluated; stale means the thing that used to prove this ran again and no longer proves it; expired is an attestation whose renewal window has passed.

Scorecards union down the tree — a service is graded by every scorecard in its ancestor chain whose selector matches it, and a subgroup cannot switch off an organisation-wide baseline.

Dependency edges are observed, not asserted

Because the platform runs the npm, Cargo and PyPI registries, an edge is discovered rather than declared: when one service publishes acme-auth and another's lockfile resolves it, that edge names the real lockfile, the real commit and the real resolved version. A service declares what it provides; the lockfile says who consumes it. Two lockfile formats are read — Cargo.lock and package-lock.json — anywhere in the tree, so a monorepo's services/checkout/Cargo.lock counts exactly as a root one does. Consumption in any other ecosystem has to be declared, in depends_on:.

A declared edge and an observed edge for the same pair coexist, and their disagreement is the finding — you declare a dependency no lockfile mentions, or your lockfile depends on something your declaration does not admit. Both are checks you can turn on.

Anything the platform does not build — a vendor API, a managed database, a team on another forge — is an external entity: named, owned, and pointed at by edges, with nothing else asserted about it. External entities never enter a score silently; every aggregate reports them as a separate unscored count.

How to

See what a repository already contains

Every repository starts life with one service, minted alongside it and covering all of it. Start here before declaring anything, because the entry you want to correct probably already exists.

Each row carries two facts per tier and they answer different questions: deployed is how far has this got, read from what is serving now, and status is is anything wrong, read from the latest attempt. A tier showing deployed with a failed status means the previous version is still serving and the attempt to replace it failed — which no single indicator can say.

A tier is not an environment. If production holds prod-eu, prod-us and prod-ap, the row still draws one stop: status is the worst of the three and deployed is true if any of them is serving. Open the service to see them apart.

Browse a group's services

If you already know the slug, fetch it directly rather than paging — slugs are unique across the organisation, so any group in it resolves the same name.

Open a service

The overview is one call that returns everything a service page shows: its repositories and path globs, its owner, its latest release and its latest pipeline run, how many merge requests are open against it, its technical-debt rollup by path, what is deployed where, its scorecard verdicts, and how many dependency edges point each way.

Everything on the overview is authorized per far end rather than per page. A service in a public group may bind paths in a private repository, and a reader who cannot see that repository gets a service with an empty repository list — not a 403, and not a hint that the repository exists.

Use the plain read when you want the entry itself without the derived panels.

Check which service owns a path

This is the question everything else rests on, and it takes up to 200 paths in one call so a client resolving a changed file set makes one request rather than one per file.

An answer with entries under overlapping means two declarations claim the same path. The winner is stable, but the overlap is worth fixing — narrow one of the globs, or add an exclude.

Declare a service

Most of the time you will declare services in .gitmoap/catalog.yaml, so the split lives in git beside the code it describes and arrives through a merge request. Declare one through the API when you are scripting a migration, or when the entry is an external entity with no code behind it.

Three rules are enforced at write time and are worth knowing before you hit them. A service that is not external must bind at least one path that includes something — exclusions alone are not a binding — and an external one must not bind any: inferring externality from a missing binding was rejected because a typo in a glob would then quietly turn every check not applicable, which reads as passing. Naming an owner group requires Maintainer standing on that group as well as on the declaring one, and naming an owner team requires that you maintain it or manage your organisation's teams. And binding a repository requires Maintainer on that repository too, so nobody can attach another team's code to a service they own; a repository you cannot write to answers 404 rather than 403, whether or not you can read it.

An owner may be a team — in the catalog file, owner: team:backend, a team of your organisation by its slug — and then the service is owned by whoever is on the team, and a code-owner approval from any of them counts. An owner may also be a person — owner: user:sam — and it satisfies the has an owner check. Prefer a group or a team anyway: a person is not a backlog, so a campaign filing work against a person-owned service falls back to the group the service is declared in, and every ownership rollup is a group-by over teams.

Correct a service

Renaming a slug, changing the owner, moving a lifecycle to deprecated, adding a runbook link — all of it is one partial update. Supply the version you read to make the write refuse rather than silently overwrite somebody else's edit.

Renaming a slug through this endpoint is deliberate and safe: everything that points at the service points at its id, so deployments, check results and dependency edges survive. Renaming a slug inside a catalog file is not the same act — it reads as a delete plus a create, because a slug is a cross-repository identifier other services resolve against.

Delete a service

Deleting a repository does something narrower and deliberately different: an auto-created service bound only to that repository is deleted with it, while a declared service is orphaned so its history survives.

Declare an environment

Declare it on the group when several repositories deploy to the same place — which is almost always right for production — and on a repository when the place belongs to that repository alone.

Two refusals to expect. Requiring approval with no approvers is refused at create time — a gate nobody can open is a deploy that can never happen, and 02:00 during an incident is the worst possible time to learn that. And a Maintainer cannot create a production-tier environment at all; that one is Owner.

List the environments a repository can deploy to

Change an environment's protection

Owner is required to change protection, to change the tier, or to change anything at all on a production-tier environment. The last of those exists so an Owner-only environment cannot be reshaped one Maintainer-level field at a time.

Who may approve is a list of approvers, each a person, a team, or a role at a group or repository — everyone holding at least that role there. With direct_only, a role counts only people given access on that group or repository itself, not those who inherit it from a group above, so an organisation Owner does not walk through every team's gate. required is how many different approvers must approve before the deploy starts, and accept_from says which approvals count: people_signed_in by default — a person approving in the web app, or in the CLI after gitmoap login — or people, which also counts a personal access token, or people_and_service_accounts. <team-id> and <group-id> below are ids from your organisation:

A deployment's approvers are always named: anyone and code owners, which an approval rule on a merge request may use, are refused here. A pipeline step deploying to the environment may narrow these approvers, never add to them.

The wait timer starts when the gate clears, not when the run reaches it. Approved, deploying in ten minutes, cancel if you spot something is what the pause is for, and a timer that had been running while an approver deliberated would already have expired by the time they pressed the button.

Give an environment its variables and secrets

Variables reach a pipeline step as environment variables. A non-secret's value is stored where the API can read it back; a secret's is stored where no read can return it, and is redacted from the step's logs.

A handful of names are refused, because a variable able to set them would point a platform-signed token at a role of your choosing: anything beginning GITMOAP_, anything beginning AWS_CONTAINER_CREDENTIALS_, and AWS_ROLE_ARN, AWS_ROLE_SESSION_NAME, AWS_WEB_IDENTITY_TOKEN_FILE and AWS_REGION. Set a region or a role on the provider connection instead, where it is authorized.

Where a name is set both on a provider connection and on the environment, the environment wins — the more specific place is the more deliberate one. What is refused rather than resolved is a collision that changes a name's secrecy: a connection secret shadowed by a plain environment value would move a credential out of the redaction list, so the run fails at resolution naming both sources. The same holds for a group or repository pipeline variable that shares a name with an environment variable and differs from it in secrecy.

A step's configuration can read a non-secret variable of the environment it deploys to as well, by writing {"$var": "WEB_S3_BUCKET"} where the value belongs, so a bucket or an endpoint declared here once serves every pipeline that deploys here. A secret cannot be read that way, because configuration is not redacted from logs. See Read a variable in a step's configuration.

Build with an environment's settings

A web app's bundle usually carries its settings inside it: the API address, the sign-in client, each VITE_* or NEXT_PUBLIC_* value is baked in when the app is built. So the step that runs the build needs the environment's values, and it must not be the step that deploys there. Set variables_from on the build step instead of environment:

The build receives the environment's non-secret variables as environment variables, and its configuration can read them with {"$var": …}. It gets nothing else from the environment: no approval wait, no lock, no secrets and no OIDC identity, and finishing it records no deployment. A secret is given only to a step that deploys there, so the build's log says how many of the environment's secrets it did not receive. A build-time secret, such as a token for uploading source maps, belongs on the step's connection or in a pipeline variable.

Two things are refused when you save the pipeline, and again when a run starts:

• One step naming both. A step that deploys already reads its own environment's variables.
• Shipping one environment's build to another. A deploy whose input was built with a different environment's variables — staging's settings bound for production — is refused, naming both steps. Build once per environment, each with that environment's variables. A build that reads no environment produces something you can deploy anywhere.

allowed_scopes applies to variables_from as it does to a deploy, because reading an environment's settings is using it. allowed_refs does not: a step that only reads variables reaches nothing, so a feature branch can build with production's settings to preview them.

Retire an environment

Archiving is the reversible operation. An archived environment leaves resolution — no new run can target it — while every deployment recorded against it stays readable. Archive with the ordinary edit; delete only an environment created by mistake.

See what is deployed

Read the deployment board

The board is services down the side, environments across the top, the current deployment in each cell — the page people actually leave open.

The rows are the services this group declares, not its whole subtree. Open a subgroup's board to see that subgroup's services; the group you opened is the one that decides the rows.

Columns are read with inheritance, so a column can be an ancestor group's environment — which is the usual case, since most repositories deploy to a production declared far above them. A nearer slug shadows a farther one, archived environments are left out, and an ancestor's environment you have no access to is dropped rather than shown empty.

Every environment you can see is a column, on every page, in slug order. Paging moves through the services, never the columns. A board that would draw more than 500 columns is refused with 400 rather than drawn short: choose the environments you want or narrow to a tier.

The board deliberately does not carry drift. Working out how far behind each cell is costs a git walk per service, environment and repository, and a forty-by-four board would be 160 of them on a page nobody closes. Ask for drift one service at a time.

Find out how far behind a deployment is

Drift is reported per repository, never averaged. A service spanning three repositories has three answers and they are rendered as three rows, because a single number combining them is confidently wrong and a wrong number gets acted on. A row shows no count when the deployed commit can no longer be read — after a force-push, or a repository move — rather than failing the whole read.

Trace what a service depends on

All three reads drop edges whose far end you cannot see and report how many they dropped, so a partial answer says so rather than looking complete. They are bounded rather than paged; each says whether its bound was reached.

See what checks exist before writing a scorecard

Thirteen derived checks ship: has_owner, human_declared, has_repository, has_pipeline, branch_protection, requires_review, released_within, deployed_within, has_runbook, has_api_spec, declared_dep_unobserved, observed_dep_undeclared and dependency_freshness. released_within takes a window in days, defaulting to 90; deployed_within takes a window defaulting to 30 days and a tier defaulting to production.

Applicability is decided by the facts a service has. Each check names what it reads — a binding, a repository, a deployment, a release, an interface — and a service with none of them resolves not applicable rather than failing, which is why a library the platform has never recorded a deployment for is never marked red for having none. The one check that reads kind rather than a fact is the API-spec check: an api or a service is expected to publish an interface description and a datastore is not. Everywhere else, kind decides which scorecards select a service; it does not excuse a check from one that already selected it.

Create a scorecard

Levels are a ladder, not a set of badges, so list them in the order you want them climbed. Grading walks them from the first and stops at the first rung whose required checks are not satisfied — a service cannot skip one, so nothing is ever graded Gold that never reached Bronze. A check counts as satisfied when it is passing or not applicable, which is what lets a library reach the top rung of a scorecard that includes a deployment check; a required check that has never been evaluated counts as unknown and does not satisfy.

A scorecard with no levels is a checklist, which is what most of them are.

Read a scorecard's results

The partition stays scorecard-wide whatever you filter by. Narrow to one service and the rows are that service's, but the counts beside them are still every service the scorecard grades — so read a per-service tally off the rows, not off the summary.

A result marked flapping means the check has changed state ten times today and the platform has stopped recording its edges. Read it as this check is not trustworthy — usually a threshold set at the noise floor, or a test that is not deterministic — and fix the check rather than the service.

Amend a scorecard, and run a campaign

A campaign turns red squares into work: a failing check whose Create work item box is ticked opens an item in the owning group's backlog, carrying a criterion bound to the check — so the item closes itself when the check passes and reopens if it regresses.

It is gated three times, and the gating is the design rather than caution. Work-item creation is off per check. The campaign is off per scorecard, so the whole set is inert until somebody switches it on. And each activation may file at most a set number of items — counted from zero each time the switch moves off to on, so a campaign paused and resumed next quarter does not start already exhausted. Four hundred services times twelve checks is 4,800 work items in one pass, which is the single most likely way this feature gets switched off across an organisation in week one.

Removing a check that a level still requires is refused, because the rung would be unreachable for ever.

Attest a check no machine can see

Some true statements about software are not measurable. We rehearsed the failover is one, and a system that demanded a metric for it would simply get nothing recorded.

Only passing and failing can be attested. stale, unknown and not_applicable are the platform's own vocabulary for what it could not determine, and letting a person write them would make nobody has looked indistinguishable from somebody said so. Attesting a derived or evidence check is refused for the same reason: a value the platform computes has exactly one writer.

Delete a scorecard

Reference

Services

Environments

Environment variables

Deployments

Scorecards