Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,30 @@ Plugins are grouped into workspaces under `workspaces/<name>/`, one per plugin f
Requirements: Node.js 22 or 24, Yarn 4 (bundled in `.yarn/releases`), and Docker for local development.

```sh
yarn install
yarn tsc # type check
yarn lint # lint all packages
yarn test # unit tests
yarn build # type check and build every package
yarn start <name> # run workspaces/<name> locally, see its README
yarn install # once, from here
yarn tsc # type check
yarn lint # lint all packages
yarn test # unit tests
yarn build # type check and build every package
```

All workspaces share one Yarn project at the repository root (one `package.json` and `yarn.lock`).
All workspaces share one Yarn project at the repository root — one `package.json` and one `yarn.lock` — but each workspace is its own entry point for running the app. To run one locally, go into it:

```sh
cd workspaces/ownership-matcher
yarn start
```

## Repository structure

```
.changeset/ changesets for versioning
workspaces/<name>/
plugins/* one directory per package
package.json workspace entry point, nests packages/* and plugins/*
packages/app dev frontend, private, never published
packages/backend dev backend, private, never published
plugins/* one directory per published package
scripts/start.js `yarn start` — database, then the two dev packages
app-config.yaml configuration for local development
docker-compose.yml services for local development
examples/ sample catalog data
Expand All @@ -39,4 +47,4 @@ workspaces/<name>/

## Adding a plugin

Run `yarn new`, pick a template, and move the generated package into `workspaces/<name>/plugins/`. Run `yarn backstage-cli repo fix --publish` to add the metadata needed for publishing. `yarn start <name>` runs the `dev/` entry points of the plugins whose plugin ID matches the workspace name, so name the workspace after the plugin ID.
Run `yarn new`, pick a template, and move the generated package into `workspaces/<name>/plugins/`. Run `yarn backstage-cli repo fix --publish` to add the metadata needed for publishing. A new workspace needs its own `package.json` nesting `packages/*` and `plugins/*`, plus a `packages/app` and `packages/backend` to run it — the root glob only reaches `workspaces/*`.
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
"node": "22 || 24"
},
"scripts": {
"start": "node scripts/start.js",
"tsc": "tsc",
"tsc:full": "tsc --skipLibCheck false --incremental false",
"build": "yarn tsc && backstage-cli repo build --all",
Expand All @@ -22,6 +21,8 @@
},
"workspaces": {
"packages": [
"workspaces/*",
"workspaces/*/packages/*",
"workspaces/*/plugins/*"
]
},
Expand Down
2 changes: 1 addition & 1 deletion tsconfig.json
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
{
"extends": "@backstage/cli/config/tsconfig.json",
"include": [
"workspaces/*/packages/*/src",
"workspaces/*/plugins/*/src",
"workspaces/*/plugins/*/config.d.ts",
"workspaces/*/plugins/*/dev",
"workspaces/*/plugins/*/migrations"
],
"exclude": ["node_modules"],
Expand Down
74 changes: 67 additions & 7 deletions workspaces/ownership-matcher/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,20 +42,80 @@ See [Statuses](plugins/ownership-matcher-backend/docs/statuses.md) and [Escalati

## Local development

From the repository root:
From this directory:

```sh
yarn start ownership-matcher # or `yarn start` while this is the only workspace
yarn start
```

This starts Postgres in Docker (`docker-compose.yml`, `127.0.0.1:54321`) and the `dev/` entry points:
This starts Postgres in Docker (`docker-compose.yml`, `127.0.0.1:54321`) and the two dev packages:

- frontend: http://localhost:3000, with the catalog, notifications, org and signals plugins
- backend: http://127.0.0.1:7007, with catalog, auth, permissions, events, notifications, signals and ownership-matcher
- `packages/app` — frontend on http://localhost:3000, with the catalog, notifications, org and signals plugins
- `packages/backend` — backend on http://127.0.0.1:7007, with catalog, auth, permissions, events, notifications, signals and ownership-matcher

Configuration is in `app-config.yaml`, plus an optional gitignored `app-config.local.yaml`. You are signed in as a guest, permissions are allow-all, and the catalog is loaded from `examples/`. The first scan runs 30 seconds after startup and flags the two sample components with a bad owner.
Configuration is in `app-config.yaml`, plus an optional gitignored `app-config.local.yaml`. You are signed in as a guest, permissions are allow-all, and the first scan runs 30 seconds after startup.

The Bitbucket Server and Microsoft Graph modules need real credentials, so the dev backend doesn't install them. To try one, configure it in `app-config.local.yaml` and add it in `plugins/ownership-matcher-backend/dev/index.ts`.
You land on a sign-in page — pick **Guest**. Without an identity every request goes out unauthenticated and the plugin reports "you are not an administrator" and "you are not a member of any groups" rather than a 401, so if you ever see those two messages together, check that you are actually signed in.

If `yarn start` fails with `Bind for 0.0.0.0:54321 failed: port is already allocated`, another project on the machine holds the database port — `docker compose ls -a` names it. The dev app also binds `127.0.0.1:7008`; if that is taken, the backend refuses to start and names the port.

### How the sample catalog is wired

The catalog is not read off disk. On startup the backend copies `examples/` into a temporary directory and serves it over HTTP on `127.0.0.1:7008` as a mock SCM server, and `app-config.yaml` declares an `integrations.*` entry for that host. Backstage only accepts its built-in integration types, so the mock borrows one (`MOCK_SCM_TYPE` in `packages/backend/src/scm/MockScmProvider.ts`) and serves its URL shape; nothing talks to a real server. Two things follow, and the plugin needs both:

- Every entity gets a `url:` `backstage.io/managed-by-location`. A `file:` location has no integration behind it, so `ScmRegistry` short-circuits before any provider is consulted — with one, entities route to a provider.
- A dev-only SCM provider (`packages/backend/src/scm/`) registers for that integration type. It supplies synthetic commit history, so `top-contributor` can score, and in-memory pull requests whose merge writes the new owner back into the served copy.

Each top-level directory under `examples/` is a mock repository, which is what lets a pull request rewrite one component's `catalog-info.yaml` without touching the others. The copy is recreated on every start, so a completed demo does not leave the catalog already fixed.

Nothing under `packages/` ships — both are `private` — and every plugin publishes `dist` only.

### What the sample data gives you

The signed-in guest is `user:default/guest`, a member of `team-example` and `team-data` — so the `?team=` selector has something to switch between — and of `dept-example` with a job title matching the escalation `titlePatterns`, which is what opens the lead-only views. `dave` leads the other department, so not every escalation in the catalog is yours.

After the first scan:

| View | Shows |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Dashboard | three open cases and a confidence distribution spread over four buckets |
| Entities | the nine failing entities, across Component, API and Resource |
| Proposals | six, three `pending` and three `possible_owner`, from 0.125 to 0.85 |
| Unresolved | six rows: two Components, two APIs, two Resources, under both failing checks — the `kind` facet has three chips |
| Scans | the startup scan, plus any you trigger |
| Pending | `orphaned-service` on `team-example` and `etl-pipeline` on `team-data` |
| My Teams | the same two, seen as the department lead |
| Escalations | empty until you reject `placeholder-owner-library` — that case escalates to `dept-example` and lands on the guest |
| History | fills up as you accept and reject |

The scores are not arbitrary. With the default weights (`top-contributor` 0.5, `org-proximity` 0.3) and a system owner scoring 0.6, the commit fixtures in `packages/backend/src/scm/fixtures.ts` produce a team that both owns the system and wrote most of the code (0.725), a contested repo (0.5375 against 0.3125), a component with a system but no commits (0.225) and one with neither (nothing at all, so the case goes `unresolved`).

### Walking a case from accepted to closed

The deadline-checker sweep raises pull requests and reconciles their outcome. It runs every 15 minutes, which is fine in production and too slow to watch, so drive it by hand:

```sh
T=$(curl -s http://localhost:7007/api/auth/guest/refresh | jq -r .backstageIdentity.token)
sweep() { curl -s -X POST -H "Authorization: Bearer $T" \
http://localhost:7007/api/ownership-matcher/.backstage/scheduler/v1/tasks/ownership-matcher-deadline-checker/trigger; }
```

Then, accepting `orphaned-service` in the UI:

1. the case goes `accepted`;
2. `sweep` — one pass raises the pull request against the mock host **and** merges it, writing the new owner into the served `catalog-info.yaml`;
3. the catalog re-reads that file within 30 seconds (`catalog.processingInterval`);
4. the next scan closes the case as `ownership_changed`.

The merge is immediate on purpose. `MERGE_AFTER_MS` in `packages/backend/src/index.ts` is `0` because a single sweep raises the PR and reconciles it in the same pass: a PR with any delay at all is still open at its only reconciliation, and `PR_RECONCILE_INTERVAL_MS` then puts the next check an hour out, stranding the case in `accepted`. Raise the constant if you want to see the open-PR state in the UI, and expect to wait out that hour.

`POST /api/ownership-matcher/scans/trigger` runs a scan without waiting for the daily schedule. The same scheduler endpoint drives proposal expiry: `ownershipMatcher.proposals.expirationMinutes` is 10, so a proposal left alone for ten minutes reaches `expired` on the next sweep.

Two statuses stay out of reach here. `to_archive` needs an escalation action and `cancelled` needs a proposal to be superseded; both depend on the escalation clock, whose `timeoutDays` has no minute-level override.

Outside production the `/leadership/*` endpoints accept `?asUser=<entityRef>`, which is the quickest way to check the lead-only views as somebody else — for example `user:default/alice`, who leads nothing.

The Bitbucket Server and Microsoft Graph modules need real credentials, so the dev backend doesn't install them. To try one, configure it in `app-config.local.yaml` and add it in `packages/backend/src/index.ts`.

## Integration tests

Expand Down
72 changes: 64 additions & 8 deletions workspaces/ownership-matcher/app-config.yaml
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@
# Configuration for `yarn start` (the plugins' dev/ entry points). Not used by the
# published packages. `yarn start` also loads app-config.local.yaml next to this
# file if it exists (gitignored), for local overrides.
# Configuration for this workspace's `yarn start` (packages/app and
# packages/backend). Not used by the published packages. scripts/start.js also
# loads app-config.local.yaml next to this file if it exists (gitignored).
app:
title: ownership-matcher dev app
baseUrl: http://localhost:3000
# Enables the app plugin's own sign-in page, which offers the `guest`
# provider. Without a sign-in page the app renders with no identity, every
# request goes out unauthenticated, and catalog, notifications and
# ownership-matcher all answer 401 — which the UI surfaces as "you are not an
# administrator" and "you are not a member of any groups".
extensions:
- sign-in-page:app

organization:
name: Development
Expand Down Expand Up @@ -31,21 +38,70 @@ backend:

auth:
providers:
guest: {}
guest:
# The provider defaults to user:development/guest, which examples/root/org.yaml
# does not define, so sign-in falls back to a token with no group
# ownership refs and every "my teams" view renders empty. Point it at the
# sample user instead, so the guest inherits group:default/team-example.
userEntityRef: user:default/guest

permission:
enabled: true

# Mock SCM server, not a real one. The dev backend serves a throwaway copy of
# examples/ on 127.0.0.1:7008 (packages/backend/src/devScmServer.ts), and this
# entry is what makes two things work at once: Backstage's URL reader can read
# the catalog files, and ownership-matcher's ScmRegistry can route an entity's
# managed-by-location to the mock SCM provider registered for this type.
# Backstage only accepts its built-in integration types, so the mock borrows
# this one and its URL shape; the key cannot be renamed to something generic.
# Without an integration for the host the registry short-circuits and no
# provider is ever consulted.
integrations:
bitbucketServer:
- host: 127.0.0.1:7008
# Explicit because the default is https://<host>/rest/api/1.0.
apiBaseUrl: http://127.0.0.1:7008/rest/api/1.0

catalog:
# Dev-only: a merged pull request writes the new owner into the served copy
# of examples/, and the case only closes once the catalog has re-read it.
# The 10-minute default would leave it looking stuck.
processingInterval:
seconds: 30
rules:
- allow: [Component, System, API, Resource, Location, User, Group]
locations:
- type: file
target: ../../examples/entities.yaml
- type: file
target: ../../examples/org.yaml
# Everything else is reached from this one document. The port is fixed by
# DEV_SCM_PORT in packages/backend/src/devScmServer.ts.
- type: url
target: http://127.0.0.1:7008/projects/dev/repos/root/browse/root.yaml

ownershipMatcher:
# The dev SCM provider ignores the token, but ScmRegistry only hands a host
# config to a provider that has one, and the real providers refuse writes
# without it — so the shape is kept honest here.
scm:
hosts:
- host: 127.0.0.1:7008
writeToken: dev-token
checks:
orphaned:
placeholderValues: [unknown]
proposals:
# Documented as "meant for testing": without it a proposal expires after
# `expirationDays` and `expired` is unreachable in a sitting. Expiry only
# fires on a deadline-checker sweep, so nothing expires behind your back
# until the next one runs.
autoExpiry: true
expirationMinutes: 10
# Enabled so the escalation-driven views are reachable: without this key
# escalation is off, every case with no candidates goes straight to
# unresolved, and /leadership/stats never reports a leader. The title
# pattern matches the guest user's spec.profile.title in examples/root/org.yaml.
escalation:
levels:
- groupFilter: Group:department
timeoutDays: 7
titlePatterns: ['^Head of ']
fallbackActors: ['user:default/guest']
4 changes: 2 additions & 2 deletions workspaces/ownership-matcher/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
name: backstage-plugins
# Postgres for the development backend, started by `yarn start`. ownership-matcher's
# Postgres for packages/backend, started by this workspace's `yarn start`. ownership-matcher's
# migrations use Postgres-only features, so SQLite isn't an option.
services:
db:
image: postgres:16
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
# `docker compose up --wait` (run by `yarn start`) waits for this, so the
# `docker compose up --wait` (run by scripts/start.js) waits for this, so the
# backend doesn't start before Postgres accepts connections.
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U postgres -h 127.0.0.1']
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# orphaned check fails. Third kind on the Unresolved tab, so its `kind` facet
# shows three chips with a count above one.
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
name: analytics-bucket
description: Placeholder owner and no parent system
spec:
type: s3-bucket
owner: unknown
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# orphaned check fails and there are no commits in
# packages/backend/src/scm/fixtures.ts, so org-proximity is the only strategy that scores it:
# 0.3 * 0.6 / (0.5 + 0.3) = 0.225, below the 0.4 notification threshold. This
# is the component that keeps `possible_owner` reachable.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: docs-portal
description: Placeholder owner, a parent system, and nobody committing to it
spec:
type: website
lifecycle: experimental
owner: unknown
system: internal-tools
32 changes: 0 additions & 32 deletions workspaces/ownership-matcher/examples/entities.yaml

This file was deleted.

Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# orphaned check fails, and both strategies point at team-data — the signed-in
# user's *second* team. Accepting here instead of on orphaned-service is what
# exercises the `?team=` selector on the user-facing tabs.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: etl-pipeline
description: Owned by a placeholder value, committed to by the data team
spec:
type: service
lifecycle: production
owner: unknown
system: data-platform
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# No system and no commits, so neither strategy finds a candidate: this is the
# one that keeps the "Unresolved" tab populated.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: legacy-batch-job
description: Placeholder owner and no parent system, so no candidates are found
spec:
type: service
lifecycle: deprecated
owner: unknown
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# zombie check fails.
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
name: legacy-queue
description: Owned by a team that doesn't exist in the catalog
spec:
type: queue
owner: group:default/team-that-was-disbanded
22 changes: 0 additions & 22 deletions workspaces/ownership-matcher/examples/org.yaml

This file was deleted.

Loading
Loading