From c7c93155d95cc2023025d9255f4745f88fb0121e Mon Sep 17 00:00:00 2001 From: Katarzyna Rak Date: Wed, 4 Nov 2026 16:11:08 +0100 Subject: [PATCH] add GitLab SCM provider module and match commit emails against spec.profile.email --- .changeset/gitlab-scm-provider.md | 5 + .changeset/profile-email-contributors.md | 6 + workspaces/ownership-matcher/README.md | 3 +- .../packages/backend/src/index.ts | 7 +- .../.eslintrc.js | 17 + .../README.md | 83 +++ .../package.json | 46 ++ .../src/GitLabScmClient.test.ts | 531 +++++++++++++++ .../src/GitLabScmClient.ts | 627 ++++++++++++++++++ .../src/GitLabScmProvider.ts | 58 ++ .../src/__testUtils__/fakeGitLabServer.ts | 435 ++++++++++++ .../src/conformance.test.ts | 63 ++ .../src/errors.test.ts | 97 +++ .../src/errors.ts | 112 ++++ .../src/index.ts | 25 + .../src/location.test.ts | 126 ++++ .../src/location.ts | 106 +++ .../src/module.test.ts | 41 ++ .../src/module.ts | 37 ++ .../ownership-matcher-backend/README.md | 2 +- .../docs/catalog-info-prs.md | 2 +- .../docs/configuration.md | 4 +- .../docs/extending.md | 2 +- .../docs/proposal-scoring.md | 2 +- .../src/service/ContributorService.test.ts | 97 ++- .../src/service/ContributorService.ts | 22 +- .../src/catalog/CatalogService.test.ts | 33 + .../src/catalog/CatalogService.ts | 37 +- .../ownership-matcher-node/src/types.ts | 2 +- yarn.lock | 14 + 30 files changed, 2613 insertions(+), 29 deletions(-) create mode 100644 .changeset/gitlab-scm-provider.md create mode 100644 .changeset/profile-email-contributors.md create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/.eslintrc.js create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/README.md create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/package.json create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.test.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmProvider.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/__testUtils__/fakeGitLabServer.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/conformance.test.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.test.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/index.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.test.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.test.ts create mode 100644 workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.ts diff --git a/.changeset/gitlab-scm-provider.md b/.changeset/gitlab-scm-provider.md new file mode 100644 index 0000000..d738434 --- /dev/null +++ b/.changeset/gitlab-scm-provider.md @@ -0,0 +1,5 @@ +--- +'@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab': minor +--- + +Added the GitLab SCM provider module. It serves `integrations.gitlab` hosts (gitlab.com and self-managed, including nested groups) with commit history for the `top-contributor` strategy and merge requests for catalog-info owner changes. Merge-request calls need `ownershipMatcher.scm.hosts[].writeToken` and never fall back to the integration token. diff --git a/.changeset/profile-email-contributors.md b/.changeset/profile-email-contributors.md new file mode 100644 index 0000000..8465d07 --- /dev/null +++ b/.changeset/profile-email-contributors.md @@ -0,0 +1,6 @@ +--- +'@stepstone-tech/backstage-plugin-ownership-matcher-backend': minor +'@stepstone-tech/backstage-plugin-ownership-matcher-node': minor +--- + +Commit authors are now first matched to catalog users by their full commit email against `spec.profile.email` (case-insensitive). The existing matching on the email local part (user name, then the `userAlias` annotation) remains as the fallback. `CatalogService.getUserData` now also returns `spec.profile.email`. diff --git a/workspaces/ownership-matcher/README.md b/workspaces/ownership-matcher/README.md index ea8209c..4536a71 100644 --- a/workspaces/ownership-matcher/README.md +++ b/workspaces/ownership-matcher/README.md @@ -38,6 +38,7 @@ See [Statuses](plugins/ownership-matcher-backend/docs/statuses.md) and [Escalati | [`@stepstone-tech/backstage-plugin-ownership-matcher-node`](plugins/ownership-matcher-node/README.md) | Extension points and contracts for modules | | [`@stepstone-tech/backstage-plugin-ownership-matcher-common`](plugins/ownership-matcher-common/README.md) | Notification origin and topic names | | [`@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-bitbucket-server`](plugins/ownership-matcher-backend-module-bitbucket-server/README.md) | Bitbucket Server SCM provider | +| [`@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab`](plugins/ownership-matcher-backend-module-gitlab/README.md) | GitLab SCM provider | | [`@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-msgraph-email`](plugins/ownership-matcher-backend-module-msgraph-email/README.md) | Email digest sender using Microsoft Graph | ## Local development @@ -115,7 +116,7 @@ Two statuses stay out of reach here. `to_archive` needs an escalation action and Outside production the `/leadership/*` endpoints accept `?asUser=`, 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`. +The Bitbucket Server, GitLab 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 diff --git a/workspaces/ownership-matcher/packages/backend/src/index.ts b/workspaces/ownership-matcher/packages/backend/src/index.ts index 7a468c8..cc7447c 100644 --- a/workspaces/ownership-matcher/packages/backend/src/index.ts +++ b/workspaces/ownership-matcher/packages/backend/src/index.ts @@ -83,7 +83,7 @@ async function main() { mergeAfterMs: MERGE_AFTER_MS, }), ); - // The Bitbucket Server and MS Graph e-mail modules need real credentials, so + // The Bitbucket Server, GitLab and MS Graph e-mail modules need real credentials, so // they are not installed here. To try one, configure it in the workspace's // app-config.local.yaml (gitignored, loaded by `yarn start`), add the package // to this package.json and install it: @@ -92,6 +92,11 @@ async function main() { // '@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-bitbucket-server' // ), // ); + // backend.add( + // import( + // '@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab' + // ), + // ); backend.start(); } diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/.eslintrc.js b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/.eslintrc.js new file mode 100644 index 0000000..1bb986e --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/.eslintrc.js @@ -0,0 +1,17 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/README.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/README.md new file mode 100644 index 0000000..aae27f4 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/README.md @@ -0,0 +1,83 @@ +# @stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab + +GitLab (gitlab.com and self-managed) SCM provider for the ownership-matcher backend. It serves `integrations.gitlab` hosts and provides: + +- commit history for the `top-contributor` proposal strategy, +- branch, commit and merge request calls for the catalog-info `spec.owner` change. + +## Installation + +```ts +// packages/backend/src/index.ts +backend.add( + import('@stepstone-tech/backstage-plugin-ownership-matcher-backend'), +); +backend.add( + import( + '@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab' + ), +); +``` + +## Configuration + +```yaml +integrations: + gitlab: + - host: gitlab.com + token: ${GITLAB_TOKEN} + # Self-managed, optionally served under a relative path: + - host: gitlab.example.com + apiBaseUrl: https://gitlab.example.com/gitlab/api/v4 + baseUrl: https://gitlab.example.com/gitlab + token: ${GITLAB_EXAMPLE_TOKEN} + +ownershipMatcher: + scm: + hosts: + # Required for the merge request flow. May reuse the integration's + # secret (writeToken: ${GITLAB_TOKEN}) if that token has the `api` scope. + - host: gitlab.com + writeToken: ${GITLAB_WRITE_TOKEN} +``` + +| Token | Used for | Scope | +| ----------------------------------------- | -------------------------------------------- | ---------- | +| `integrations.gitlab[].token` | Commit history | `read_api` | +| `ownershipMatcher.scm.hosts[].writeToken` | The whole merge request flow, reads included | `api` | + +The `writeToken`'s user needs at least the Developer role on the projects and must be allowed to push to new branches. The merge request flow never falls back to the integration token: without a `writeToken`, a warning is logged at startup and merge request jobs fail with `auth`, so writes are always an explicit opt-in. Without an integration token, commit history is read anonymously (public projects only). Requests time out after 30 seconds. + +## Behaviour + +- **Locations**: `managed-by-location` URLs of the form `/[/...]//-/blob//`. `` is used as the merge request's target branch. +- **Commit history**: the newest commits on the default branch (`GET /projects/:id/repository/commits`). `per_page` follows the strategy's `commitsLimit` (capped at 100, paging through larger limits). Each commit's `author_email` is matched to catalog users by the core plugin. +- **File edits**: one commit via the Files API, guarded by the file's `last_commit_id`. A concurrent change yields a `conflict`, and the core plugin re-reads the file and retries. +- **Merge requests**: one open merge request per source branch. A duplicate is reused, and merge requests from forks are ignored. States map as `opened`/`locked` → `open`, `merged` → `merged`, `closed` → `declined`. +- **Reviewers**: GitLab user ids. The acceptor is found by searching users by email. The default reviewers are the active eligible approvers of the project's approval rules (excluding `any_approver`, `report_approver` and `code_owner` rules) that apply to the target branch. + +## Error mapping + +Checked in this order: + +| GitLab response | `ScmError` kind | +| --------------------------------------------------------------- | ---------------------------------------------------------------- | +| 400/409 "changed since you started editing" or "already exists" | `conflict` (`createBranch` returns `exists`) | +| Archived, read-only or maintenance mode (non-404) | `read-only` | +| 401, 403 | `auth` | +| 404 | `not-found` (`readFile` and `getPullRequest` return `undefined`) | +| 409 | `conflict` (`createPullRequest` returns `reused`) | +| 429 | `rate-limited` | +| 400, 422 | `invalid` | +| 5xx, network errors, timeouts | `unavailable` | +| Anything else | `unknown` | + +A reviewer that isn't a numeric GitLab user id is rejected as `invalid`, with the reviewer named, so the core plugin retries without it. + +## Limitations + +- **Branch names with `/` in locations**: in a blob URL, only the first segment after `/-/blob/` is taken as the branch, so `-/blob/feature/x/catalog-info.yaml` reads as branch `feature` (same as Backstage's own GitLab URL parsing). Register catalog files from branches without `/`. +- **Commit SHAs in locations**: a location pinned to a full commit SHA is treated as the default branch. +- **Finding reviewers by email**: on gitlab.com, a non-admin token only finds users by their **public** email, and the search response carries no email to compare. A single search hit is then accepted, unless its name or username contains the email (GitLab's search also matches those). If the acceptor can't be found, the merge request is opened without them as a reviewer. +- **Approval rules** are a Premium feature. On Free tier projects (403/404) there are no default reviewers. GitLab still enforces any approval rules on the merge request itself. Group-based rules can make the reviewer list long. +- **Archived projects**: GitLab may reject writes to an archived project with a plain 403, which maps to `auth`. diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/package.json b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/package.json new file mode 100644 index 0000000..0dc7b68 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/package.json @@ -0,0 +1,46 @@ +{ + "name": "@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab", + "description": "GitLab SCM provider for the ownership-matcher backend", + "version": "0.0.0", + "main": "src/index.ts", + "types": "src/index.ts", + "license": "Apache-2.0", + "publishConfig": { + "access": "public", + "main": "dist/index.cjs.js", + "types": "dist/index.d.ts" + }, + "backstage": { + "role": "backend-plugin-module", + "pluginId": "ownership-matcher", + "pluginPackage": "@stepstone-tech/backstage-plugin-ownership-matcher-backend" + }, + "scripts": { + "start": "backstage-cli package start", + "build": "backstage-cli package build", + "lint": "backstage-cli package lint", + "test": "backstage-cli package test", + "clean": "backstage-cli package clean", + "prepack": "backstage-cli package prepack", + "postpack": "backstage-cli package postpack" + }, + "dependencies": { + "@backstage/backend-plugin-api": "^1.10.1", + "@backstage/integration": "^2.1.2", + "@stepstone-tech/backstage-plugin-ownership-matcher-node": "workspace:^" + }, + "devDependencies": { + "@backstage/backend-test-utils": "^1.11.7", + "@backstage/cli": "^0.36.6", + "@backstage/config": "^1.3.9", + "@stepstone-tech/backstage-plugin-ownership-matcher-backend": "workspace:^" + }, + "files": [ + "dist" + ], + "repository": { + "type": "git", + "url": "https://github.com/stepstone-tech/backstage-plugins.git", + "directory": "workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab" + } +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.test.ts new file mode 100644 index 0000000..12722a7 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.test.ts @@ -0,0 +1,531 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { mockServices } from '@backstage/backend-test-utils'; +import { + isScmError, + type ScmError, +} from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; +import { GitLabScmClient } from './GitLabScmClient'; +import { gitlabRepo } from './location'; +import { + API, + createFakeGitLabServer, + HOST, + ORIGIN, + PROJECT_PATH, +} from './__testUtils__/fakeGitLabServer'; + +const server = createFakeGitLabServer(); +const REPO = gitlabRepo(ORIGIN, PROJECT_PATH); + +function makeClient( + opts: { + writeToken?: string | null; + token?: string | null; + fetch?: typeof fetch; + } = {}, +) { + return new GitLabScmClient({ + config: { + host: HOST, + apiBaseUrl: API, + baseUrl: ORIGIN, + ...(opts.token === null ? {} : { token: opts.token ?? 'read-token' }), + }, + writeToken: + opts.writeToken === null ? undefined : opts.writeToken ?? 'write-token', + logger: mockServices.logger.mock(), + fetch: opts.fetch ?? server.fetch, + }); +} + +async function scmError(promise: Promise): Promise { + const err = await promise.then( + () => undefined, + e => e, + ); + if (!isScmError(err)) + throw new Error(`expected an ScmError, got ${String(err)}`); + return err; +} + +beforeEach(() => server.reset()); + +describe('GitLabScmClient credentials', () => { + it('reads history with the integration token', async () => { + await makeClient().history.getCommits(REPO, { limit: 5 }); + expect(server.requests[0].headers.Authorization).toBe('Bearer read-token'); + }); + + it('runs the merge-request flow, reads included, with the write token', async () => { + await makeClient().pullRequests.readFile(REPO, 'catalog-info.yaml', 'main'); + expect(server.requests.map(r => r.headers.Authorization)).toEqual([ + 'Bearer write-token', + ]); + }); + + it('refuses the merge-request flow without a write token — never falls back to the read credentials', async () => { + const client = makeClient({ writeToken: null }); + const err = await scmError(client.pullRequests.getDefaultBranch(REPO)); + expect(err.kind).toBe('auth'); + expect(err.message).toContain('writeToken'); + expect(server.requests).toHaveLength(0); + }); + + it('reads history anonymously without any token', async () => { + const client = makeClient({ writeToken: null, token: null }); + await expect( + client.history.getCommits(REPO, { limit: 5 }), + ).resolves.toHaveLength(3); + expect(server.requests[0].headers.Authorization).toBeUndefined(); + }); + + it('maps network failures to `unavailable`', async () => { + const client = makeClient({ + fetch: async () => { + throw new Error('ECONNRESET'); + }, + }); + const err = await scmError(client.history.getCommits(REPO, { limit: 1 })); + expect(err.kind).toBe('unavailable'); + }); +}); + +describe('GitLabScmClient history', () => { + const manyCommits = (n: number) => + Array.from({ length: n }, (_, i) => ({ + id: `c${i}`, + author_email: `dev${i % 5}@example.com`, + author_name: `dev${i % 5}`, + })); + + it('maps author_email and author_name, newest first', async () => { + await expect( + makeClient().history.getCommits(REPO, { limit: 25 }), + ).resolves.toEqual([ + { id: 'a1', author: { email: 'alice@example.com', name: 'alice' } }, + { id: 'b1', author: { email: 'bob@example.com', name: 'bob' } }, + { id: 'a2', author: { email: 'alice@example.com', name: 'alice' } }, + ]); + const url = server.requests[0].url; + expect(url.pathname).toBe( + `/api/v4/projects/${encodeURIComponent(PROJECT_PATH)}/repository/commits`, + ); + expect(url.searchParams.get('per_page')).toBe('25'); + }); + + it('passes per_page from the limit (GitLab defaults to 20)', async () => { + server.state.commits = manyCommits(40); + const commits = await makeClient().history.getCommits(REPO, { limit: 30 }); + expect(commits).toHaveLength(30); + expect(server.requests).toHaveLength(1); + expect(server.requests[0].url.searchParams.get('per_page')).toBe('30'); + }); + + it('pages through limits above 100', async () => { + server.state.commits = manyCommits(300); + const commits = await makeClient().history.getCommits(REPO, { + limit: 250, + }); + expect(commits).toHaveLength(250); + expect(commits[249].id).toBe('c249'); + expect( + server.requests.map(r => [ + r.url.searchParams.get('per_page'), + r.url.searchParams.get('page'), + ]), + ).toEqual([ + ['100', '1'], + ['100', '2'], + ['100', '3'], + ]); + }); + + it('stops at the last page', async () => { + server.state.commits = manyCommits(150); + const commits = await makeClient().history.getCommits(REPO, { + limit: 500, + }); + expect(commits).toHaveLength(150); + expect(server.requests).toHaveLength(2); + }); + + it('stops on a short page when GitLab sends no x-next-page header', async () => { + server.state.commits = manyCommits(150); + server.state.nextPageHeader = false; + const commits = await makeClient().history.getCommits(REPO, { + limit: 500, + }); + expect(commits).toHaveLength(150); + expect(server.requests).toHaveLength(2); + }); + + it('throws `not-found` for a missing project', async () => { + server.fail(/repository\/commits/, 404, '404 Project Not Found'); + const err = await scmError( + makeClient().history.getCommits(REPO, { limit: 5 }), + ); + expect(err.kind).toBe('not-found'); + }); +}); + +describe('GitLabScmClient files and branches', () => { + it('reads a file, decoding base64, with last_commit_id as the revision', async () => { + await expect( + makeClient().pullRequests.readFile( + REPO, + 'src/My Service/catalog-info.yaml', + 'main', + ), + ).resolves.toEqual({ content: 'kind: System\n', revision: 'c1' }); + const url = server.requests[0].url; + expect(url.pathname).toContain( + `/repository/files/${encodeURIComponent( + 'src/My Service/catalog-info.yaml', + )}`, + ); + expect(url.searchParams.get('ref')).toBe('main'); + }); + + it('returns undefined for a missing file or branch', async () => { + const prs = makeClient().pullRequests; + await expect(prs.readFile(REPO, 'nope.yaml', 'main')).resolves.toBe( + undefined, + ); + await expect( + prs.readFile(REPO, 'catalog-info.yaml', 'no-branch'), + ).resolves.toBeUndefined(); + }); + + it('updates a file with PUT and last_commit_id', async () => { + const prs = makeClient().pullRequests; + await prs.commitFile(REPO, 'catalog-info.yaml', { + content: 'kind: Component\nspec: {}\n', + message: 'update owner', + branch: 'main', + revision: 'c1', + }); + const req = server.requests[0]; + expect(req.method).toBe('PUT'); + expect(req.body).toEqual({ + branch: 'main', + content: 'kind: Component\nspec: {}\n', + commit_message: 'update owner', + last_commit_id: 'c1', + }); + await expect( + prs.readFile(REPO, 'catalog-info.yaml', 'main'), + ).resolves.toMatchObject({ content: 'kind: Component\nspec: {}\n' }); + }); + + it('creates a missing file with POST and no revision', async () => { + const prs = makeClient().pullRequests; + await prs.commitFile(REPO, 'new/catalog-info.yaml', { + content: 'kind: Component\n', + message: 'add', + branch: 'main', + }); + expect(server.requests[0].method).toBe('POST'); + expect(server.requests[0].body).not.toHaveProperty('last_commit_id'); + }); + + it('reports creating a file that already exists as `conflict`', async () => { + const err = await scmError( + makeClient().pullRequests.commitFile(REPO, 'catalog-info.yaml', { + content: 'x', + message: 'add', + branch: 'main', + }), + ); + expect(err.kind).toBe('conflict'); + }); + + it('creates a branch and reports an existing one as `exists`', async () => { + const prs = makeClient().pullRequests; + await expect(prs.createBranch(REPO, 'feature/x', 'main')).resolves.toBe( + 'created', + ); + expect(server.requests[0].body).toEqual({ + branch: 'feature/x', + ref: 'main', + }); + await expect(prs.createBranch(REPO, 'feature/x', 'main')).resolves.toBe( + 'exists', + ); + }); + + it('throws `read-only` instead of `exists` for an archived project', async () => { + server.fail( + /POST .*repository\/branches/, + 403, + 'This project is archived and cannot be modified', + ); + const err = await scmError( + makeClient().pullRequests.createBranch(REPO, 'feature/x', 'main'), + ); + expect(err.kind).toBe('read-only'); + }); + + it('reads the default branch', async () => { + server.state.defaultBranch = 'trunk'; + await expect( + makeClient().pullRequests.getDefaultBranch(REPO), + ).resolves.toBe('trunk'); + }); + + it('rejects an empty project path as `invalid`', async () => { + const err = await scmError( + makeClient().pullRequests.getDefaultBranch({ ...REPO, path: 'a//b' }), + ); + expect(err.kind).toBe('invalid'); + }); +}); + +describe('GitLabScmClient merge requests', () => { + const opts = { + title: 'Set owner', + description: 'Ownership', + fromBranch: 'feature/owner', + toBranch: 'main', + }; + + beforeEach(async () => { + await makeClient().pullRequests.createBranch(REPO, opts.fromBranch, 'main'); + server.requests.length = 0; + }); + + it('creates an MR with reviewer ids and returns iid + web_url', async () => { + const { status, pr } = await makeClient().pullRequests.createPullRequest( + REPO, + { ...opts, reviewers: ['7', '7'] }, + ); + expect(status).toBe('created'); + expect(pr).toEqual({ + id: '1', + url: `${ORIGIN}/${PROJECT_PATH}/-/merge_requests/1`, + }); + expect(server.requests[0].body).toEqual({ + source_branch: 'feature/owner', + target_branch: 'main', + title: 'Set owner', + description: 'Ownership', + reviewer_ids: [7], + }); + }); + + it('rejects non-numeric reviewer ids as `invalid`, naming them', async () => { + const err = await scmError( + makeClient().pullRequests.createPullRequest(REPO, { + ...opts, + reviewers: ['7', 'jdoe'], + }), + ); + expect(err.kind).toBe('invalid'); + expect(err.rejectedReviewers).toEqual(['jdoe']); + expect(server.requests).toHaveLength(0); + }); + + it('ignores a fork MR with the same source branch name', async () => { + server.addForkMergeRequest(opts.fromBranch); + const prs = makeClient().pullRequests; + await expect( + prs.findOpenPullRequest(REPO, opts.fromBranch), + ).resolves.toBeUndefined(); + const created = await prs.createPullRequest(REPO, opts); + expect(created.status).toBe('created'); + await expect( + prs.findOpenPullRequest(REPO, opts.fromBranch), + ).resolves.toEqual(created.pr); + }); + + it.each([ + ['opened', 'open', undefined], + ['locked', 'open', undefined], + ['merged', 'merged', '2026-10-02T00:00:00.000Z'], + ['closed', 'declined', '2026-10-02T00:00:00.000Z'], + ] as const)('maps state %s to %s', async (gitlabState, state, closedAt) => { + const prs = makeClient().pullRequests; + const { pr } = await prs.createPullRequest(REPO, opts); + server.setMergeRequestState(Number(pr.id), gitlabState); + const read = await prs.getPullRequest(REPO, pr.id); + expect(read).toEqual({ + ...pr, + state, + createdAt: new Date('2026-10-01T00:00:00.000Z'), + ...(closedAt ? { closedAt: new Date(closedAt) } : {}), + }); + }); + + it('throws on an unknown MR state', async () => { + const prs = makeClient().pullRequests; + const { pr } = await prs.createPullRequest(REPO, opts); + server.setMergeRequestState(Number(pr.id), 'weird' as any); + const err = await scmError(prs.getPullRequest(REPO, pr.id)); + expect(err.kind).toBe('unknown'); + }); + + it('updates title, description and adds reviewers, keeping existing ones', async () => { + server.state.users.push({ id: 8, username: 'other', state: 'active' }); + const prs = makeClient().pullRequests; + const { pr } = await prs.createPullRequest(REPO, { + ...opts, + reviewers: ['7'], + }); + server.requests.length = 0; + + await expect( + prs.updatePullRequest(REPO, pr, { + title: 'New title', + description: 'New description', + addReviewers: ['7', '8'], + }), + ).resolves.toBe('updated'); + expect(server.requests[1].method).toBe('PUT'); + expect(server.requests[1].body).toEqual({ + title: 'New title', + description: 'New description', + reviewer_ids: [7, 8], + }); + }); + + it('leaves reviewers untouched when none are added', async () => { + const prs = makeClient().pullRequests; + const { pr } = await prs.createPullRequest(REPO, opts); + server.requests.length = 0; + await prs.updatePullRequest(REPO, pr, { + title: 'New title', + description: opts.description, + addReviewers: [], + }); + expect(server.requests[1].body).not.toHaveProperty('reviewer_ids'); + }); + + it('reports `unchanged` without writing when nothing differs', async () => { + const prs = makeClient().pullRequests; + const { pr } = await prs.createPullRequest(REPO, { + ...opts, + reviewers: ['7'], + }); + server.requests.length = 0; + await expect( + prs.updatePullRequest(REPO, pr, { + title: opts.title, + description: opts.description, + addReviewers: ['7'], + }), + ).resolves.toBe('unchanged'); + expect(server.requests.map(r => r.method)).toEqual(['GET']); + }); +}); + +describe('GitLabScmClient reviewers', () => { + it('resolves a user by public email, case-insensitively', async () => { + await expect( + makeClient().pullRequests.resolveReviewer(REPO, 'jane.doe@example.com'), + ).resolves.toBe('7'); + expect(server.requests[0].url.searchParams.get('search')).toBe( + 'jane.doe@example.com', + ); + }); + + it('accepts a single active hit when no email is returned', async () => { + server.state.users = [{ id: 9, username: 'sam', state: 'active' }]; + const fetchWithSearchHit: typeof fetch = async (input, init) => { + const url = new URL(String(input)); + if (url.pathname === '/api/v4/users') + return new Response(JSON.stringify(server.state.users), { + status: 200, + }); + return server.fetch(input, init); + }; + await expect( + makeClient({ fetch: fetchWithSearchHit }).pullRequests.resolveReviewer( + REPO, + 'sam@example.com', + ), + ).resolves.toBe('9'); + }); + + it('returns undefined for ambiguous, blocked or missing users', async () => { + const respond = + (users: unknown[]): typeof fetch => + async () => + new Response(JSON.stringify(users), { status: 200 }); + const resolve = (users: unknown[]) => + makeClient({ fetch: respond(users) }).pullRequests.resolveReviewer( + REPO, + 'x@example.com', + ); + await expect(resolve([])).resolves.toBeUndefined(); + await expect( + resolve([ + { id: 1, state: 'active' }, + { id: 2, state: 'active' }, + ]), + ).resolves.toBeUndefined(); + await expect( + resolve([{ id: 1, state: 'blocked', public_email: 'x@example.com' }]), + ).resolves.toBeUndefined(); + }); + + it('rejects a single hit that matched by name rather than email', async () => { + const resolve = (users: unknown[]) => + makeClient({ + fetch: async () => new Response(JSON.stringify(users), { status: 200 }), + }).pullRequests.resolveReviewer(REPO, 'x@example.com'); + await expect( + resolve([{ id: 1, state: 'active', name: 'Mail X@Example.com' }]), + ).resolves.toBeUndefined(); + await expect( + resolve([{ id: 2, state: 'active', name: 'Xavier', username: 'xav' }]), + ).resolves.toBe('2'); + }); + + it('returns active approvers of rules that apply to the target branch', async () => { + const prs = makeClient().pullRequests; + await expect( + prs.getDefaultReviewers(REPO, { fromBranch: 'f', toBranch: 'main' }), + ).resolves.toEqual(['11']); + await expect( + prs.getDefaultReviewers(REPO, { + fromBranch: 'f', + toBranch: 'release/1.0', + }), + ).resolves.toEqual(['11', '13']); + }); + + it('returns no default reviewers when approval rules are unavailable', async () => { + server.state.approvalRulesAvailable = false; + await expect( + makeClient().pullRequests.getDefaultReviewers(REPO, { + fromBranch: 'f', + toBranch: 'main', + }), + ).resolves.toEqual([]); + }); + + it('propagates other approval-rule failures', async () => { + server.fail(/approval_rules/, 500, 'Internal Server Error'); + const err = await scmError( + makeClient().pullRequests.getDefaultReviewers(REPO, { + fromBranch: 'f', + toBranch: 'main', + }), + ); + expect(err.kind).toBe('unavailable'); + }); +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.ts new file mode 100644 index 0000000..1767716 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmClient.ts @@ -0,0 +1,627 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type { LoggerService } from '@backstage/backend-plugin-api'; +import { + getGitLabRequestOptions, + type GitLabIntegrationConfig, +} from '@backstage/integration'; +import { + ScmError, + type ScmClient, + type ScmCommit, + type ScmFile, + type ScmFileLocation, + type ScmHistoryCapability, + type ScmPullRequest, + type ScmPullRequestCapability, + type ScmPullRequestRef, + type ScmPullRequestState, + type ScmRepoRef, +} from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; +import { toScmError } from './errors'; +import { parseGitLabLocation, trimTrailingSlashes } from './location'; + +const REQUEST_TIMEOUT_MS = 30_000; +/** GitLab's maximum `per_page`. */ +const MAX_PER_PAGE = 100; + +export interface GitLabScmClientOptions { + config: GitLabIntegrationConfig; + /** + * Token for the whole merge-request flow (reads included). Never falls back + * to the integration's read credentials: without it, every `pullRequests` + * call throws `auth`. + */ + writeToken?: string; + logger: LoggerService; + /** Host-restricted fetch from `ScmProviderContext`. */ + fetch: typeof fetch; +} + +interface Raw { + status: number; + ok: boolean; + text: string; + headers: Headers; +} + +interface GitLabUserJson { + id: number; + username?: string; + name?: string; + state?: string; + email?: string; + public_email?: string; +} + +interface GitLabMergeRequestJson { + iid: number; + web_url?: string; + state?: string; + title?: string; + description?: string | null; + source_project_id?: number; + target_project_id?: number; + created_at?: string; + merged_at?: string | null; + closed_at?: string | null; + reviewers?: GitLabUserJson[]; +} + +interface GitLabApprovalRuleJson { + rule_type?: string; + eligible_approvers?: GitLabUserJson[]; + users?: GitLabUserJson[]; + protected_branches?: Array<{ name?: string }>; + applies_to_all_protected_branches?: boolean; +} + +/** `locked` is a transient state while GitLab merges the MR. */ +const MR_STATES: Record = { + opened: 'open', + locked: 'open', + merged: 'merged', + closed: 'declined', +}; + +/** Approval rule types that don't name required approvers. */ +const NON_REVIEWER_RULE_TYPES = new Set([ + 'any_approver', + 'report_approver', + 'code_owner', +]); + +/** + * GitLab (gitlab.com or self-managed) implementation of the ownership-matcher + * SCM contract: commit history via the integration's credentials, and + * branches, commits and merge requests via the per-host write token, falling + * back to the integration token. + * + * Every request goes through the host-restricted `fetch` it is given. Failed + * responses throw {@link ScmError}; normal outcomes (missing file, existing + * branch, already-open MR) are returned. + */ +export class GitLabScmClient implements ScmClient { + readonly history: ScmHistoryCapability; + readonly pullRequests: ScmPullRequestCapability; + /** e.g. `https://gitlab.com/api/v4`. */ + private readonly apiBase: string; + private readonly readHeaders: Record; + /** `undefined` without a write token: the merge-request flow is refused. */ + private readonly writeHeaders: Record | undefined; + + constructor(private readonly options: GitLabScmClientOptions) { + const { config, writeToken } = options; + this.apiBase = trimTrailingSlashes(config.apiBaseUrl); + this.readHeaders = getGitLabRequestOptions(config).headers; + this.writeHeaders = writeToken + ? getGitLabRequestOptions(config, writeToken).headers + : undefined; + this.history = { getCommits: (repo, opts) => this.getCommits(repo, opts) }; + this.pullRequests = { + getDefaultBranch: repo => this.getDefaultBranch(repo), + readFile: (repo, path, branch) => this.readFile(repo, path, branch), + createBranch: (repo, name, startPoint) => + this.createBranch(repo, name, startPoint), + commitFile: (repo, path, opts) => this.commitFile(repo, path, opts), + findOpenPullRequest: (repo, fromBranch) => + this.findOpenPullRequest(repo, fromBranch), + getPullRequest: (repo, id) => this.getPullRequest(repo, id), + createPullRequest: (repo, opts) => this.createPullRequest(repo, opts), + updatePullRequest: (repo, pr, desired) => + this.updatePullRequest(repo, pr, desired), + resolveReviewer: (_repo, email) => this.resolveReviewer(email), + getDefaultReviewers: (repo, opts) => this.getDefaultReviewers(repo, opts), + }; + } + + parseLocation(url: string): ScmFileLocation | undefined { + return parseGitLabLocation(url, this.options.config); + } + + // ── history ──────────────────────────────────────────────────────────────── + + /** + * Newest-first commits on the default branch. `per_page` follows `limit` + * (GitLab's default is 20), capped at 100; larger limits page through. + */ + private async getCommits( + repo: ScmRepoRef, + { limit }: { limit: number }, + ): Promise { + const perPage = Math.max(1, Math.min(limit, MAX_PER_PAGE)); + const commits: ScmCommit[] = []; + let page = 1; + while (commits.length < limit) { + const res = await this.send( + 'getCommits', + `${this.projectBase( + repo, + )}/repository/commits?per_page=${perPage}&page=${page}`, + { headers: this.readHeaders }, + ); + if (!res.ok) throw toScmError(res.status, res.text); + const values = parseJson< + Array<{ id: string; author_email?: string; author_name?: string }> + >(res.text); + if (!Array.isArray(values)) + throw new ScmError('unknown', 'Commits response is not a list'); + for (const c of values) { + commits.push({ + id: c.id, + author: { email: c.author_email ?? '', name: c.author_name ?? '' }, + }); + } + const next = res.headers.get('x-next-page'); + if (next !== null) { + if (!next) break; + page = Number(next); + if (!Number.isFinite(page)) break; + } else { + if (values.length < perPage) break; + page++; + } + } + return commits.slice(0, limit); + } + + // ── merge requests ───────────────────────────────────────────────────────── + + private async getDefaultBranch(repo: ScmRepoRef): Promise { + const data = await this.json<{ default_branch?: string }>( + 'getDefaultBranch', + this.projectBase(repo), + ); + if (!data.default_branch) + throw new ScmError('unknown', 'Project response has no default_branch'); + return data.default_branch; + } + + /** + * Content via the Files API; revision = `last_commit_id` (the commit that + * last modified the file), which GitLab checks on update. + */ + private async readFile( + repo: ScmRepoRef, + path: string, + branch: string, + ): Promise { + const res = await this.send( + 'readFile', + `${this.fileUrl(repo, path)}?ref=${encodeURIComponent(branch)}`, + ); + if (res.status === 404) return undefined; + if (!res.ok) throw toScmError(res.status, res.text); + const file = parseJson<{ + content?: string; + encoding?: string; + last_commit_id?: string; + }>(res.text); + if (typeof file.content !== 'string' || !file.last_commit_id) { + throw new ScmError( + 'unknown', + `File response for ${path} on ${branch} has no content or last_commit_id`, + ); + } + const content = + file.encoding === 'base64' + ? Buffer.from(file.content, 'base64').toString('utf8') + : file.content; + return { content, revision: file.last_commit_id }; + } + + private async createBranch( + repo: ScmRepoRef, + name: string, + startPoint: string, + ): Promise<'created' | 'exists'> { + const res = await this.send( + 'createBranch', + `${this.projectBase(repo)}/repository/branches`, + { method: 'POST', json: { branch: name, ref: startPoint } }, + ); + if (res.ok) return 'created'; + const err = toScmError(res.status, res.text); + // "Branch already exists" — unless the project is archived/read-only. + if (err.kind === 'conflict') return 'exists'; + throw err; + } + + /** + * One commit via the Files API: update (PUT, guarded by `last_commit_id`) + * with a revision, create (POST) without. A stale revision, or creating a + * file that exists, is a `conflict`. + */ + private async commitFile( + repo: ScmRepoRef, + path: string, + opts: { + content: string; + message: string; + branch: string; + revision?: string; + }, + ): Promise { + const res = await this.send('commitFile', this.fileUrl(repo, path), { + method: opts.revision ? 'PUT' : 'POST', + json: { + branch: opts.branch, + content: opts.content, + commit_message: opts.message, + ...(opts.revision ? { last_commit_id: opts.revision } : {}), + }, + }); + if (!res.ok) throw toScmError(res.status, res.text); + } + + /** The open MR from `fromBranch` of this project (not a fork's same-named branch). */ + private async findOpenPullRequest( + repo: ScmRepoRef, + fromBranch: string, + ): Promise { + const params = new URLSearchParams({ + state: 'opened', + source_branch: fromBranch, + per_page: '20', + }); + const mrs = await this.json( + 'findOpenPullRequest', + `${this.projectBase(repo)}/merge_requests?${params}`, + ); + if (!Array.isArray(mrs)) + throw new ScmError('unknown', 'Merge requests response is not a list'); + const mr = mrs.find( + m => + m.source_project_id === undefined || + m.source_project_id === m.target_project_id, + ); + return mr ? toPrRef(mr) : undefined; + } + + private async getPullRequest( + repo: ScmRepoRef, + id: string, + ): Promise { + const res = await this.send( + 'getPullRequest', + `${this.projectBase(repo)}/merge_requests/${encodeURIComponent(id)}`, + ); + if (res.status === 404) return undefined; + if (!res.ok) throw toScmError(res.status, res.text); + const mr = parseJson(res.text); + const state = MR_STATES[mr.state ?? '']; + if (!state) + throw new ScmError( + 'unknown', + `Merge request ${id} has unknown state ${mr.state}`, + ); + const closed = mr.merged_at ?? mr.closed_at; + return { + ...toPrRef(mr), + state, + ...(mr.created_at ? { createdAt: new Date(mr.created_at) } : {}), + ...(state !== 'open' && closed ? { closedAt: new Date(closed) } : {}), + }; + } + + /** A duplicate (409 — an open MR for the source branch exists) is returned as `reused`. */ + private async createPullRequest( + repo: ScmRepoRef, + opts: { + title: string; + description: string; + fromBranch: string; + toBranch: string; + reviewers?: string[]; + }, + ): Promise<{ status: 'created' | 'reused'; pr: ScmPullRequestRef }> { + const res = await this.send( + 'createPullRequest', + `${this.projectBase(repo)}/merge_requests`, + { + method: 'POST', + json: { + source_branch: opts.fromBranch, + target_branch: opts.toBranch, + title: opts.title, + description: opts.description, + reviewer_ids: toUserIds(opts.reviewers ?? []), + }, + }, + ); + if (res.ok) + return { + status: 'created', + pr: toPrRef(parseJson(res.text)), + }; + const err = toScmError(res.status, res.text); + // A duplicate-MR 409 is reused — unless the project is archived/read-only. + if (err.kind === 'conflict') { + const existing = await this.findOpenPullRequest(repo, opts.fromBranch); + if (existing) return { status: 'reused', pr: existing }; + } + throw err; + } + + /** + * Fetches the MR first — for its current reviewers, which `reviewer_ids` + * replaces — and only writes when something differs. Existing reviewers are + * kept. + */ + private async updatePullRequest( + repo: ScmRepoRef, + pr: ScmPullRequestRef, + desired: { title: string; description: string; addReviewers?: string[] }, + ): Promise<'updated' | 'unchanged'> { + const url = `${this.projectBase(repo)}/merge_requests/${encodeURIComponent( + pr.id, + )}`; + const current = await this.json( + 'updatePullRequest', + url, + ); + const existing = (current.reviewers ?? []).map(r => r.id); + const known = new Set(existing); + const added = toUserIds(desired.addReviewers ?? []).filter( + id => !known.has(id), + ); + if ( + current.title === desired.title && + (current.description ?? '') === desired.description && + added.length === 0 + ) { + return 'unchanged'; + } + + const res = await this.send('updatePullRequest', url, { + method: 'PUT', + json: { + title: desired.title, + description: desired.description, + ...(added.length ? { reviewer_ids: [...existing, ...added] } : {}), + }, + }); + if (!res.ok) throw toScmError(res.status, res.text); + return 'updated'; + } + + /** + * The id of the active GitLab user with this email. Users whose returned + * `email`/`public_email` matches (case-insensitively) win; otherwise a single + * active search hit is taken. On gitlab.com a non-admin token only finds + * users by their *public* email, and the list response carries no email. + * `search` also matches name and username, so a single hit whose name or + * username contains the email is rejected: the match must come from the + * email. + */ + private async resolveReviewer(email: string): Promise { + const params = new URLSearchParams({ search: email, per_page: '20' }); + const users = await this.json( + 'resolveReviewer', + `${this.apiBase}/users?${params}`, + ); + if (!Array.isArray(users)) return undefined; + const active = users.filter(u => isActive(u) && typeof u.id === 'number'); + const lower = email.toLowerCase(); + const exact = active.find( + u => + u.email?.toLowerCase() === lower || + u.public_email?.toLowerCase() === lower, + ); + if (exact) return String(exact.id); + if (active.length !== 1) return undefined; + const [only] = active; + const matchedByName = [only.name, only.username].some(v => + v?.toLowerCase().includes(lower), + ); + return matchedByName ? undefined : String(only.id); + } + + /** + * Users named by the project's approval rules that apply to `toBranch`. + * GitLab enforces those rules on every MR itself; requesting the approvers + * as reviewers notifies them. Approval rules are a paid feature: a 403/404 + * (Free tier) means no default reviewers. + */ + private async getDefaultReviewers( + repo: ScmRepoRef, + { toBranch }: { fromBranch: string; toBranch: string }, + ): Promise { + const res = await this.send( + 'getDefaultReviewers', + `${this.projectBase(repo)}/approval_rules?per_page=${MAX_PER_PAGE}`, + ); + if (res.status === 403 || res.status === 404) return []; + if (!res.ok) throw toScmError(res.status, res.text); + const rules = parseJson(res.text); + if (!Array.isArray(rules)) + throw new ScmError('unknown', 'Approval rules response is not a list'); + + const ids = new Set(); + for (const rule of rules) { + if (NON_REVIEWER_RULE_TYPES.has(rule.rule_type ?? '')) continue; + if (!ruleAppliesTo(rule, toBranch)) continue; + for (const user of rule.eligible_approvers ?? rule.users ?? []) { + if (typeof user.id === 'number' && isActive(user)) + ids.add(String(user.id)); + } + } + return [...ids]; + } + + // ── transport ────────────────────────────────────────────────────────────── + + private projectBase(repo: ScmRepoRef): string { + if (!repo.path || repo.path.split('/').some(s => !s)) { + throw new ScmError('invalid', `Not a GitLab project path: ${repo.path}`); + } + return `${this.apiBase}/projects/${encodeURIComponent(repo.path)}`; + } + + /** The Files API takes the whole path as one encoded segment (`/` → `%2F`). */ + private fileUrl(repo: ScmRepoRef, path: string): string { + const clean = path.split('/').filter(Boolean).join('/'); + return `${this.projectBase(repo)}/repository/files/${encodeURIComponent( + clean, + )}`; + } + + /** GET returning parsed JSON; any non-2xx throws. */ + private async json( + op: string, + url: string, + opts: { headers?: Record } = {}, + ): Promise { + const res = await this.send(op, url, opts); + if (!res.ok) throw toScmError(res.status, res.text); + return parseJson(res.text); + } + + /** + * One request with a timeout. Uses the write headers unless told otherwise + * (the whole MR flow, reads included, runs on the write credential, so a + * read never succeeds with a token that couldn't do the following write). + * Without any token such requests throw `auth` before any I/O. + * Network failures throw `unavailable`. + */ + private async send( + op: string, + url: string, + opts: { + method?: string; + headers?: Record; + json?: unknown; + } = {}, + ): Promise { + const auth = opts.headers ?? this.writeHeaders; + if (!auth) { + throw new ScmError( + 'auth', + `No write token configured for ${this.options.config.host} (ownershipMatcher.scm.hosts[].writeToken)`, + ); + } + const headers: Record = { + Accept: 'application/json', + ...auth, + }; + let body: string | undefined; + if (opts.json !== undefined) { + headers['Content-Type'] = 'application/json'; + body = JSON.stringify(opts.json); + } + try { + const res = await this.options.fetch(url, { + method: opts.method ?? 'GET', + headers, + body, + signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), + }); + return { + status: res.status, + ok: res.ok, + text: await res.text(), + headers: res.headers, + }; + } catch (err) { + const message = err instanceof Error ? err.message : String(err); + this.options.logger.warn(`GitLab ${op} request failed: ${message}`); + throw new ScmError('unavailable', message, { cause: err }); + } + } +} + +function toPrRef(mr: GitLabMergeRequestJson): ScmPullRequestRef { + return { id: String(mr.iid), url: mr.web_url ?? '' }; +} + +function isActive(user: GitLabUserJson): boolean { + return user.state === undefined || user.state === 'active'; +} + +/** + * Reviewer ids are GitLab user ids as strings. Anything else can't be a + * reviewer: reject it as `invalid` (naming it) so core retries without it. + */ +function toUserIds(reviewers: string[]): number[] { + const rejected = reviewers.filter(r => !/^\d+$/.test(r)); + if (rejected.length) { + throw new ScmError( + 'invalid', + `Not GitLab user ids: ${rejected.join(', ')}`, + { rejectedReviewers: rejected }, + ); + } + return [...new Set(reviewers.map(Number))]; +} + +/** + * Whether an approval rule covers `branch`: rules without protected branches + * (or for all protected branches) apply to every target; otherwise one of the + * protected-branch names, which may contain `*` wildcards, must match. + */ +function ruleAppliesTo(rule: GitLabApprovalRuleJson, branch: string): boolean { + const names = (rule.protected_branches ?? []) + .map(b => b.name) + .filter((n): n is string => Boolean(n)); + if (rule.applies_to_all_protected_branches || names.length === 0) return true; + return names.some(name => wildcardMatch(name, branch)); +} + +function wildcardMatch(pattern: string, value: string): boolean { + const parts = pattern.split('*'); + if (parts.length === 1) return pattern === value; + if (!value.startsWith(parts[0])) return false; + let pos = parts[0].length; + for (let i = 1; i < parts.length - 1; i++) { + const idx = value.indexOf(parts[i], pos); + if (idx < 0) return false; + pos = idx + parts[i].length; + } + const last = parts[parts.length - 1]; + return value.length - last.length >= pos && value.endsWith(last); +} + +function parseJson(text: string): T { + try { + return JSON.parse(text) as T; + } catch { + throw new ScmError( + 'unknown', + `Unparseable GitLab response: ${text.slice(0, 200)}`, + ); + } +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmProvider.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmProvider.ts new file mode 100644 index 0000000..e867d62 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/GitLabScmProvider.ts @@ -0,0 +1,58 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type { GitLabIntegration } from '@backstage/integration'; +import type { + ScmClient, + ScmProvider, + ScmProviderContext, +} from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; +import { GitLabScmClient } from './GitLabScmClient'; +import { GITLAB_TYPE } from './location'; + +/** + * Ownership-matcher SCM provider for `integrations.gitlab` hosts. Commit + * history uses the integration credentials; branch, commit and merge-request + * calls need `ownershipMatcher.scm.hosts[].writeToken` for the host and are + * refused (`auth`) without it; they never fall back to the integration's read + * credentials. + * + * @public + */ +export class GitLabScmProvider implements ScmProvider { + readonly type = GITLAB_TYPE; + + createClient(ctx: ScmProviderContext): ScmClient { + if (ctx.integration.type !== GITLAB_TYPE) { + throw new Error( + `GitLabScmProvider cannot serve a '${ctx.integration.type}' integration`, + ); + } + const { config } = ctx.integration as GitLabIntegration; + const writeToken = ctx.hostConfig?.writeToken; + if (!writeToken) { + ctx.logger.warn( + `No write token for ${config.host} (ownershipMatcher.scm.hosts[].writeToken); branch, commit and merge-request calls are refused for this host`, + ); + } + return new GitLabScmClient({ + config, + writeToken, + logger: ctx.logger, + fetch: ctx.fetch, + }); + } +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/__testUtils__/fakeGitLabServer.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/__testUtils__/fakeGitLabServer.ts new file mode 100644 index 0000000..256255f --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/__testUtils__/fakeGitLabServer.ts @@ -0,0 +1,435 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * In-memory GitLab REST v4 API covering the endpoints the client uses, for + * the project `acme/platform/repo`. `fetch` serves it; `requests` records + * every call for assertions; `fail` makes the next matching request return an + * error response. + */ + +export const HOST = 'gitlab.example.com'; +export const ORIGIN = `https://${HOST}`; +export const API = `${ORIGIN}/api/v4`; +export const PROJECT_PATH = 'acme/platform/repo'; +const PROJECT_ID = 42; + +interface FileState { + content: string; + commit: string; +} + +interface MergeRequest { + iid: number; + sourceBranch: string; + targetBranch: string; + sourceProjectId: number; + title: string; + description: string; + reviewerIds: number[]; + state: 'opened' | 'merged' | 'closed' | 'locked'; + createdAt: string; + mergedAt?: string; + closedAt?: string; +} + +interface User { + id: number; + username: string; + state: string; + public_email?: string; +} + +interface ApprovalRule { + rule_type: string; + eligible_approvers?: Array<{ id: number; username: string; state: string }>; + protected_branches?: Array<{ name: string }>; + applies_to_all_protected_branches?: boolean; +} + +export interface RecordedRequest { + method: string; + url: URL; + headers: Record; + body: unknown; +} + +const defaultUsers: User[] = [ + { + id: 7, + username: 'jdoe', + state: 'active', + public_email: 'Jane.Doe@example.com', + }, +]; + +const defaultApprovalRules: ApprovalRule[] = [ + { + rule_type: 'regular', + eligible_approvers: [ + { id: 11, username: 'lead', state: 'active' }, + { id: 12, username: 'gone', state: 'blocked' }, + ], + protected_branches: [], + }, + { + rule_type: 'regular', + eligible_approvers: [{ id: 13, username: 'release-lead', state: 'active' }], + protected_branches: [{ name: 'release/*' }], + }, + { + rule_type: 'any_approver', + eligible_approvers: [{ id: 14, username: 'anyone', state: 'active' }], + }, +]; + +export function createFakeGitLabServer() { + let commitCounter = 1; + const nextCommit = () => `c${++commitCounter}`; + const state = { + defaultBranch: 'main', + branches: new Map>(), + mrs: [] as MergeRequest[], + users: [] as User[], + approvalRules: [] as ApprovalRule[], + /** `false`: approval rules unavailable (Free tier) → 403. */ + approvalRulesAvailable: true, + commits: [] as Array<{ + id: string; + author_email: string; + author_name: string; + }>, + /** Whether commit pages carry `x-next-page`. */ + nextPageHeader: true, + }; + const requests: RecordedRequest[] = []; + const failures: Array<{ match: RegExp; status: number; body: string }> = []; + + function reset() { + commitCounter = 1; + state.defaultBranch = 'main'; + state.branches = new Map([ + [ + 'main', + new Map([ + ['catalog-info.yaml', { content: 'kind: Component\n', commit: 'c1' }], + [ + 'src/My Service/catalog-info.yaml', + { content: 'kind: System\n', commit: 'c1' }, + ], + ]), + ], + ]); + state.mrs = []; + state.users = defaultUsers.map(u => ({ ...u })); + state.approvalRules = defaultApprovalRules.map(r => ({ ...r })); + state.approvalRulesAvailable = true; + state.commits = [ + { id: 'a1', author_email: 'alice@example.com', author_name: 'alice' }, + { id: 'b1', author_email: 'bob@example.com', author_name: 'bob' }, + { id: 'a2', author_email: 'alice@example.com', author_name: 'alice' }, + ]; + state.nextPageHeader = true; + requests.length = 0; + failures.length = 0; + } + reset(); + + const json = ( + status: number, + body?: unknown, + headers: Record = {}, + ) => + new Response(body === undefined ? '' : JSON.stringify(body), { + status, + headers, + }); + + const userJson = (id: number) => { + const user = state.users.find(u => u.id === id); + return { id, username: user?.username ?? `user${id}`, state: 'active' }; + }; + + const toJson = (mr: MergeRequest) => ({ + iid: mr.iid, + project_id: PROJECT_ID, + source_project_id: mr.sourceProjectId, + target_project_id: PROJECT_ID, + source_branch: mr.sourceBranch, + target_branch: mr.targetBranch, + title: mr.title, + description: mr.description, + state: mr.state, + created_at: mr.createdAt, + merged_at: mr.mergedAt ?? null, + closed_at: mr.closedAt ?? null, + reviewers: mr.reviewerIds.map(userJson), + web_url: `${ORIGIN}/${PROJECT_PATH}/-/merge_requests/${mr.iid}`, + }); + + const fetchImpl: typeof fetch = async (input, init) => { + const url = new URL( + typeof input === 'string' || input instanceof URL + ? input.toString() + : input.url, + ); + const method = init?.method ?? 'GET'; + const body = + typeof init?.body === 'string' ? JSON.parse(init.body) : undefined; + requests.push({ + method, + url, + headers: { ...(init?.headers as Record) }, + body, + }); + + // Decode per segment: `%2F` inside a segment (project id, file path) stays + // part of that segment, as on GitLab. + const segments = url.pathname.split('/').map(decodeURIComponent); + const route = `${method} ${segments.join('/')}`; + const failure = failures.findIndex(f => f.match.test(route)); + if (failure >= 0) { + const [f] = failures.splice(failure, 1); + return new Response(f.body, { status: f.status }); + } + + // ['', 'api', 'v4', ...rest] + if (segments[1] !== 'api' || segments[2] !== 'v4') + return json(404, { message: '404 Not Found' }); + const rest = segments.slice(3); + + if (method === 'GET' && rest.length === 1 && rest[0] === 'users') { + const search = (url.searchParams.get('search') ?? '').toLowerCase(); + return json( + 200, + state.users.filter( + u => + u.public_email?.toLowerCase() === search || + u.username.toLowerCase().includes(search), + ), + ); + } + + if (rest[0] !== 'projects') return json(404, { message: '404 Not Found' }); + if (rest[1] !== PROJECT_PATH && rest[1] !== String(PROJECT_ID)) + return json(404, { message: '404 Project Not Found' }); + const sub = rest.slice(2); + + if (method === 'GET' && sub.length === 0) { + return json(200, { + id: PROJECT_ID, + path_with_namespace: PROJECT_PATH, + default_branch: state.defaultBranch, + }); + } + + if (method === 'GET' && sub.join('/') === 'repository/commits') { + const perPage = Number(url.searchParams.get('per_page') ?? 20); + const page = Number(url.searchParams.get('page') ?? 1); + const slice = state.commits.slice((page - 1) * perPage, page * perPage); + const hasNext = page * perPage < state.commits.length; + return json( + 200, + slice, + state.nextPageHeader + ? { 'x-next-page': hasNext ? String(page + 1) : '' } + : {}, + ); + } + + if (sub[0] === 'repository' && sub[1] === 'files' && sub.length === 3) { + const filePath = sub[2]; + if (method === 'GET') { + const ref = url.searchParams.get('ref') ?? state.defaultBranch; + const file = state.branches.get(ref)?.get(filePath); + if (!file) return json(404, { message: '404 File Not Found' }); + return json(200, { + file_path: filePath, + encoding: 'base64', + content: Buffer.from(file.content, 'utf8').toString('base64'), + last_commit_id: file.commit, + blob_id: `blob-${file.commit}`, + }); + } + const req = body as { + branch: string; + content: string; + commit_message: string; + last_commit_id?: string; + }; + const files = state.branches.get(req.branch); + if (!files) + return json(400, { + message: 'You can only create or edit files when you are on a branch', + }); + const current = files.get(filePath); + if (method === 'POST') { + if (current) + return json(400, { + message: 'A file with this name already exists', + }); + } else if (method === 'PUT') { + if (!current) + return json(400, { message: "A file with this name doesn't exist" }); + if (req.last_commit_id && req.last_commit_id !== current.commit) { + return json(400, { + message: + 'You are attempting to update a file that has changed since you started editing it.', + }); + } + } else { + return json(405, { message: '405 Method Not Allowed' }); + } + files.set(filePath, { content: req.content, commit: nextCommit() }); + return json(method === 'POST' ? 201 : 200, { + file_path: filePath, + branch: req.branch, + }); + } + + if (method === 'POST' && sub.join('/') === 'repository/branches') { + const { branch, ref } = body as { branch: string; ref: string }; + if (state.branches.has(branch)) + return json(400, { message: 'Branch already exists' }); + const start = state.branches.get(ref); + if (!start) return json(400, { message: 'Invalid reference name' }); + state.branches.set(branch, new Map(start)); + return json(201, { name: branch }); + } + + if (sub[0] === 'merge_requests' && sub.length === 1) { + if (method === 'GET') { + const st = url.searchParams.get('state'); + const source = url.searchParams.get('source_branch'); + return json( + 200, + state.mrs + .filter( + m => + (!st || m.state === st) && + (!source || m.sourceBranch === source), + ) + .map(toJson), + ); + } + if (method === 'POST') { + const req = body as { + source_branch: string; + target_branch: string; + title: string; + description: string; + reviewer_ids?: number[]; + }; + const dup = state.mrs.find( + m => + m.state === 'opened' && + m.sourceBranch === req.source_branch && + m.sourceProjectId === PROJECT_ID, + ); + if (dup) { + return json(409, { + message: [ + `Another open merge request already exists for this source branch: !${dup.iid}`, + ], + }); + } + const mr: MergeRequest = { + iid: state.mrs.length + 1, + sourceBranch: req.source_branch, + targetBranch: req.target_branch, + sourceProjectId: PROJECT_ID, + title: req.title, + description: req.description, + // Like GitLab, unknown reviewer ids are silently dropped. + reviewerIds: (req.reviewer_ids ?? []).filter(id => + state.users.some(u => u.id === id), + ), + state: 'opened', + createdAt: '2026-10-01T00:00:00.000Z', + }; + state.mrs.push(mr); + return json(201, toJson(mr)); + } + } + + if (sub[0] === 'merge_requests' && sub.length === 2) { + const mr = state.mrs.find(m => String(m.iid) === sub[1]); + if (!mr) return json(404, { message: '404 Not found' }); + if (method === 'GET') return json(200, toJson(mr)); + if (method === 'PUT') { + const req = body as { + title?: string; + description?: string; + reviewer_ids?: number[]; + }; + if (req.title !== undefined) mr.title = req.title; + if (req.description !== undefined) mr.description = req.description; + if (req.reviewer_ids !== undefined) mr.reviewerIds = req.reviewer_ids; + return json(200, toJson(mr)); + } + } + + if (method === 'GET' && sub.join('/') === 'approval_rules') { + if (!state.approvalRulesAvailable) + return json(403, { message: '403 Forbidden' }); + return json(200, state.approvalRules); + } + + return json(404, { message: `no route ${route}` }); + }; + + return { + state, + requests, + reset, + fetch: fetchImpl, + /** Make the next request whose `METHOD /decoded/path` matches return `status` with a GitLab error body. */ + fail(match: RegExp, status: number, message: unknown = 'boom') { + failures.push({ match, status, body: JSON.stringify({ message }) }); + }, + /** Change a file on `branch` behind the client's back. */ + touch(branch: string, path: string) { + const file = state.branches.get(branch)!.get(path)!; + file.content += '# changed\n'; + file.commit = nextCommit(); + }, + /** Add an MR from a fork whose source branch has the given name. */ + addForkMergeRequest(sourceBranch: string) { + state.mrs.push({ + iid: state.mrs.length + 1, + sourceBranch, + targetBranch: state.defaultBranch, + sourceProjectId: 999, + title: 'From a fork', + description: '', + reviewerIds: [], + state: 'opened', + createdAt: '2026-10-01T00:00:00.000Z', + }); + }, + /** Set an MR's state, e.g. after a merge. */ + setMergeRequestState( + iid: number, + next: MergeRequest['state'], + at = '2026-10-02T00:00:00.000Z', + ) { + const mr = state.mrs.find(m => m.iid === iid)!; + mr.state = next; + if (next === 'merged') mr.mergedAt = at; + if (next === 'closed') mr.closedAt = at; + }, + }; +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/conformance.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/conformance.test.ts new file mode 100644 index 0000000..9a8a625 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/conformance.test.ts @@ -0,0 +1,63 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { ConfigReader } from '@backstage/config'; +import { ScmIntegrations } from '@backstage/integration'; +import { describeScmProviderConformance } from '@stepstone-tech/backstage-plugin-ownership-matcher-node/testUtils'; +import { GitLabScmProvider } from './GitLabScmProvider'; +import { + API, + createFakeGitLabServer, + HOST, + ORIGIN, + PROJECT_PATH, +} from './__testUtils__/fakeGitLabServer'; + +const server = createFakeGitLabServer(); +const integration = ScmIntegrations.fromConfig( + new ConfigReader({ + integrations: { + gitlab: [{ host: HOST, apiBaseUrl: API, token: 'read-token' }], + }, + }), +).byHost(HOST)!; + +describeScmProviderConformance(new GitLabScmProvider(), { + fakeServer: { + integration, + hostConfig: { host: HOST, writeToken: 'write-token' }, + fetch: server.fetch, + reset: server.reset, + location: { + url: `${ORIGIN}/${PROJECT_PATH}/-/blob/main/catalog-info.yaml`, + expected: { + repo: { + type: 'gitlab', + host: HOST, + path: PROJECT_PATH, + webUrl: `${ORIGIN}/${PROJECT_PATH}`, + }, + path: 'catalog-info.yaml', + ref: 'main', + }, + }, + unparseableUrl: `${ORIGIN}/${PROJECT_PATH}`, + baseBranch: 'main', + async makeRevisionStale(location, branch) { + server.touch(branch, location.path); + }, + }, +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.test.ts new file mode 100644 index 0000000..737fee5 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.test.ts @@ -0,0 +1,97 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { gitlabErrorMessage, toScmError } from './errors'; + +const body = (message: unknown) => JSON.stringify({ message }); + +describe('gitlabErrorMessage', () => { + it('reads a string message', () => { + expect(gitlabErrorMessage(body('404 Project Not Found'))).toBe( + '404 Project Not Found', + ); + }); + + it('joins a list of messages', () => { + expect( + gitlabErrorMessage( + body([ + 'Another open merge request already exists for this source branch: !1', + ]), + ), + ).toBe( + 'Another open merge request already exists for this source branch: !1', + ); + }); + + it('flattens a field → messages object', () => { + expect( + gitlabErrorMessage( + body({ base: ['Something went wrong'], title: ["can't be blank"] }), + ), + ).toBe("Something went wrong; title can't be blank"); + }); + + it('reads OAuth-style errors', () => { + expect( + gitlabErrorMessage( + JSON.stringify({ + error: 'insufficient_scope', + error_description: 'The request requires higher privileges', + }), + ), + ).toBe('insufficient_scope: The request requires higher privileges'); + }); + + it('falls back to a truncated raw body', () => { + expect(gitlabErrorMessage('x'.repeat(500))).toHaveLength(200); + }); +}); + +describe('toScmError', () => { + it.each([ + [ + 400, + 'You are attempting to update a file that has changed since you started editing it.', + 'conflict', + ], + [400, 'Branch already exists', 'conflict'], + [400, 'A file with this name already exists', 'conflict'], + [403, 'This project is archived and cannot be modified', 'read-only'], + [503, 'GitLab is in maintenance mode', 'read-only'], + [404, 'Archived project not found', 'not-found'], + [401, '401 Unauthorized', 'auth'], + [403, '403 Forbidden', 'auth'], + [404, '404 Not Found', 'not-found'], + [409, 'Another open merge request already exists', 'conflict'], + [409, 'Something else', 'conflict'], + [429, 'Retry later', 'rate-limited'], + [400, 'Invalid reference name', 'invalid'], + [422, 'Unprocessable', 'invalid'], + [500, 'Internal Server Error', 'unavailable'], + [502, 'Bad gateway', 'unavailable'], + [418, 'teapot', 'unknown'], + ])('maps %i %j to %s', (status, message, kind) => { + const err = toScmError(status, body(message)); + expect(err.kind).toBe(kind); + expect(err.httpStatus).toBe(status); + expect(err.message).toBe(message); + }); + + it('uses the HTTP status when the body is empty', () => { + expect(toScmError(500, '').message).toBe('HTTP 500'); + }); +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.ts new file mode 100644 index 0000000..1c2d277 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/errors.ts @@ -0,0 +1,112 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { + ScmError, + type ScmErrorKind, +} from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; + +interface GitLabErrorBody { + /** + * A string, a list of strings (`["Another open merge request already + * exists..."]`), or field → messages for validation errors + * (`{ base: ['...'] }`). + */ + message?: string | string[] | Record; + error?: string; + error_description?: string; +} + +/** + * GitLab's error message: `message` (flattening a field → messages object), + * else `error`/`error_description`, falling back to a truncated body. + */ +export function gitlabErrorMessage(text: string): string { + try { + const body = JSON.parse(text) as GitLabErrorBody; + if (typeof body.message === 'string' && body.message) return body.message; + if (Array.isArray(body.message)) { + const parts = body.message + .filter(m => m !== undefined && m !== null && m !== '') + .map(String); + if (parts.length) return parts.join('; '); + } + if (body.message && typeof body.message === 'object') { + const parts = Object.entries(body.message).flatMap(([field, value]) => { + const messages = Array.isArray(value) ? value : [value]; + return messages + .filter(m => m !== undefined && m !== null && m !== '') + .map(m => (field === 'base' ? String(m) : `${field} ${String(m)}`)); + }); + if (parts.length) return parts.join('; '); + } + const error = [body.error, body.error_description] + .filter(Boolean) + .join(': '); + if (error) return error; + } catch { + // Not JSON — use the raw body. + } + return text.slice(0, 200); +} + +/** + * GitLab reports a stale `last_commit_id` ("You are attempting to update a + * file that has changed since you started editing it.") and an existing + * branch or file ("Branch already exists", "A file with this name already + * exists") as 400s. Both mean "conflict" in the SCM contract. + */ +function isConflictMessage(message: string): boolean { + return /changed since you started editing|already exists/i.test(message); +} + +/** + * Archived projects and GitLab's read-only (maintenance/migration) mode reject + * writes with statuses that otherwise mean auth or availability problems. + * Detect them by the error text so callers back off instead of treating them + * as permanent auth failures or retrying quickly. + */ +function isReadOnly(message: string): boolean { + return /archiv|read[- ]?only|maintenance mode/i.test(message); +} + +/** Map a failed GitLab response onto an {@link ScmError}. */ +export function toScmError(status: number, text: string): ScmError { + const message = gitlabErrorMessage(text); + let kind: ScmErrorKind; + if ((status === 400 || status === 409) && isConflictMessage(message)) { + kind = 'conflict'; + } else if (isReadOnly(message) && status !== 404) { + kind = 'read-only'; + } else if (status === 401 || status === 403) { + kind = 'auth'; + } else if (status === 404) { + kind = 'not-found'; + } else if (status === 409) { + kind = 'conflict'; + } else if (status === 429) { + kind = 'rate-limited'; + } else if (status === 400 || status === 422) { + kind = 'invalid'; + } else if (status >= 500) { + kind = 'unavailable'; + } else { + kind = 'unknown'; + } + return new ScmError(kind, message || `HTTP ${status}`, { + httpStatus: status, + }); +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/index.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/index.ts new file mode 100644 index 0000000..200e902 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/index.ts @@ -0,0 +1,25 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * GitLab SCM provider for the ownership-matcher backend. + * + * @packageDocumentation + */ +export { ownershipMatcherModuleGitLab as default } from './module'; +export { ownershipMatcherModuleGitLab } from './module'; +export { GitLabScmProvider } from './GitLabScmProvider'; +export { gitlabRepo } from './location'; diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.test.ts new file mode 100644 index 0000000..c022136 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.test.ts @@ -0,0 +1,126 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { gitlabRepo, parseGitLabLocation } from './location'; + +const GITLAB_COM = { host: 'gitlab.com', baseUrl: 'https://gitlab.com' }; +const SELF_MANAGED = { + host: 'code.example.com', + baseUrl: 'https://code.example.com/gitlab', +}; + +describe('gitlabRepo', () => { + it('builds the repo ref with the project page as webUrl', () => { + expect(gitlabRepo('https://gitlab.com', 'acme/platform/svc')).toEqual({ + type: 'gitlab', + host: 'gitlab.com', + path: 'acme/platform/svc', + webUrl: 'https://gitlab.com/acme/platform/svc', + }); + }); + + it('keeps a relative base path and drops trailing slashes', () => { + expect( + gitlabRepo('https://code.example.com/gitlab/', 'acme/svc').webUrl, + ).toBe('https://code.example.com/gitlab/acme/svc'); + }); +}); + +describe('parseGitLabLocation', () => { + it('parses a blob URL in a nested group', () => { + expect( + parseGitLabLocation( + 'https://gitlab.com/acme/platform/team/svc/-/blob/main/catalog-info.yaml', + GITLAB_COM, + ), + ).toEqual({ + repo: { + type: 'gitlab', + host: 'gitlab.com', + path: 'acme/platform/team/svc', + webUrl: 'https://gitlab.com/acme/platform/team/svc', + }, + path: 'catalog-info.yaml', + ref: 'main', + }); + }); + + it('decodes path segments and keeps nested file paths', () => { + expect( + parseGitLabLocation( + 'https://gitlab.com/acme/svc/-/blob/develop/src/My%20Service/catalog-info.yaml?ref_type=heads', + GITLAB_COM, + ), + ).toMatchObject({ + repo: { path: 'acme/svc' }, + path: 'src/My Service/catalog-info.yaml', + ref: 'develop', + }); + }); + + it('drops a commit SHA ref', () => { + const location = parseGitLabLocation( + 'https://gitlab.com/acme/svc/-/blob/0123456789abcdef0123456789abcdef01234567/catalog-info.yaml', + GITLAB_COM, + ); + expect(location?.path).toBe('catalog-info.yaml'); + expect(location).not.toHaveProperty('ref'); + }); + + it('handles a GitLab served under a relative path', () => { + expect( + parseGitLabLocation( + 'https://code.example.com/gitlab/acme/svc/-/blob/main/catalog-info.yaml', + SELF_MANAGED, + ), + ).toEqual({ + repo: { + type: 'gitlab', + host: 'code.example.com', + path: 'acme/svc', + webUrl: 'https://code.example.com/gitlab/acme/svc', + }, + path: 'catalog-info.yaml', + ref: 'main', + }); + expect( + parseGitLabLocation( + 'https://code.example.com/acme/svc/-/blob/main/catalog-info.yaml', + SELF_MANAGED, + ), + ).toBeUndefined(); + }); + + it.each([ + ['another host', 'https://evil.example.com/acme/svc/-/blob/main/c.yaml'], + ['the repo root', 'https://gitlab.com/acme/svc'], + ['a tree URL', 'https://gitlab.com/acme/svc/-/tree/main/docs'], + ['a blob URL without a file', 'https://gitlab.com/acme/svc/-/blob/main/'], + ['a directory path', 'https://gitlab.com/acme/svc/-/blob/main/docs/'], + ['a legacy blob URL', 'https://gitlab.com/acme/svc/blob/main/c.yaml'], + [ + 'an empty group segment', + 'https://gitlab.com/acme//svc/-/blob/main/c.yaml', + ], + [ + 'a malformed escape', + 'https://gitlab.com/acme/svc/-/blob/main/%E0%A4%A.yaml', + ], + ['not a URL', 'not a url'], + ])('returns undefined for %s', (_name, url) => { + expect(parseGitLabLocation(url, GITLAB_COM)).toBeUndefined(); + }); +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.ts new file mode 100644 index 0000000..1e8b392 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/location.ts @@ -0,0 +1,106 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type { + ScmFileLocation, + ScmRepoRef, +} from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; + +export const GITLAB_TYPE = 'gitlab'; + +/** Drop trailing `/`s. A loop, not `/\/+$/`, which backtracks quadratically on long `/` runs. */ +export function trimTrailingSlashes(value: string): string { + let end = value.length; + while (end > 0 && value[end - 1] === '/') end--; + return value.slice(0, end); +} + +/** A full commit SHA (SHA-1 or SHA-256): a pinned commit, not a branch. */ +const COMMIT_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i; + +/** + * The {@link ScmRepoRef} of a GitLab project: `path` is the full project path + * including any (nested) groups, e.g. `group/sub/project`; `webUrl` its page. + * + * @public + */ +export function gitlabRepo(baseUrl: string, projectPath: string): ScmRepoRef { + // `baseUrl` may carry a relative path, e.g. `https://host/gitlab`. + const url = new URL(baseUrl); + const base = `${url.origin}${trimTrailingSlashes(url.pathname)}`; + return { + type: GITLAB_TYPE, + host: url.host, + path: projectPath, + webUrl: `${base}/${projectPath + .split('/') + .map(encodeURIComponent) + .join('/')}`, + }; +} + +/** + * Parse a `managed-by-location` target of the form + * `/[/...]//-/blob//`. + * Only URLs on `host` (and under `baseUrl`'s relative path, for a GitLab + * served under e.g. `/gitlab`) are accepted. Directory (`/-/tree/`) and + * repository-root URLs are not file locations. + * + * `ref` is taken as the first segment after `/-/blob/`, so a branch name + * containing `/` can't be told apart from the file path (as in Backstage's own + * GitLab URL parsing). A full commit SHA is dropped: it pins a commit, not a + * branch to raise a merge request against. + */ +export function parseGitLabLocation( + url: string, + config: { host: string; baseUrl: string }, +): ScmFileLocation | undefined { + let parsed: URL; + let base: URL; + try { + parsed = new URL(url); + base = new URL(config.baseUrl); + } catch { + return undefined; + } + if (parsed.host !== config.host) return undefined; + + const prefix = trimTrailingSlashes(base.pathname); + if (prefix && !parsed.pathname.startsWith(`${prefix}/`)) return undefined; + const rest = parsed.pathname.slice(prefix.length); + + const match = /^\/(.+?)\/-\/blob\/([^/]+)\/(.+)$/.exec(rest); + if (!match) return undefined; + + let projectPath: string; + let ref: string; + let path: string; + try { + projectPath = match[1].split('/').map(decodeURIComponent).join('/'); + ref = decodeURIComponent(match[2]); + path = match[3].split('/').map(decodeURIComponent).join('/'); + } catch { + return undefined; + } + if (projectPath.split('/').some(segment => !segment)) return undefined; + if (!path || path.endsWith('/')) return undefined; + + return { + repo: gitlabRepo(`${parsed.origin}${prefix}`, projectPath), + path, + ...(ref && !COMMIT_SHA.test(ref) ? { ref } : {}), + }; +} diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.test.ts new file mode 100644 index 0000000..42ed2b9 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.test.ts @@ -0,0 +1,41 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { mockServices, startTestBackend } from '@backstage/backend-test-utils'; +// Test-only: start the real plugin to check the module registers into it. +// eslint-disable-next-line @backstage/no-mixed-plugin-imports +import { ownershipMatcherPlugin } from '@stepstone-tech/backstage-plugin-ownership-matcher-backend'; +import { ownershipMatcherModuleGitLab } from './module'; + +describe('ownershipMatcherModuleGitLab', () => { + it('registers the gitlab provider with the ownership-matcher plugin', async () => { + const logger = mockServices.logger.mock(); + await startTestBackend({ + features: [ + ownershipMatcherPlugin, + ownershipMatcherModuleGitLab, + logger.factory, + ], + }); + + expect(logger.info).toHaveBeenCalledWith( + 'Ownership-matcher SCM providers: gitlab', + ); + expect(logger.warn).not.toHaveBeenCalledWith( + expect.stringMatching(/No ownership-matcher SCM provider/), + ); + }); +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.ts new file mode 100644 index 0000000..a6a0ac6 --- /dev/null +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab/src/module.ts @@ -0,0 +1,37 @@ +/* + * Copyright 2026 The Stepstone Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { createBackendModule } from '@backstage/backend-plugin-api'; +import { ownershipMatcherScmExtensionPoint } from '@stepstone-tech/backstage-plugin-ownership-matcher-node'; +import { GitLabScmProvider } from './GitLabScmProvider'; + +/** + * Registers the GitLab SCM provider with the ownership-matcher plugin. + * + * @public + */ +export const ownershipMatcherModuleGitLab = createBackendModule({ + pluginId: 'ownership-matcher', + moduleId: 'gitlab', + register(env) { + env.registerInit({ + deps: { scm: ownershipMatcherScmExtensionPoint }, + async init({ scm }) { + scm.addProvider(new GitLabScmProvider()); + }, + }); + }, +}); diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/README.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/README.md index bc01e26..3362294 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/README.md +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/README.md @@ -15,7 +15,7 @@ backend.add( ); ``` -Requires the catalog, notifications, events and permission backends. Add an SCM provider module (for example [Bitbucket Server](../ownership-matcher-backend-module-bitbucket-server/README.md)) for commit-based proposals and catalog-info PRs. +Requires the catalog, notifications, events and permission backends. Add an SCM provider module (for example [Bitbucket Server](../ownership-matcher-backend-module-bitbucket-server/README.md) or [GitLab](../ownership-matcher-backend-module-gitlab/README.md)) for commit-based proposals and catalog-info PRs. ## Configuration diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/catalog-info-prs.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/catalog-info-prs.md index 182df31..c63feb5 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/catalog-info-prs.md +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/catalog-info-prs.md @@ -2,7 +2,7 @@ When a case is accepted, the plugin opens a pull request that sets `spec.owner` to the accepted team in the entity's `catalog-info.yaml`. The file is found through the `backstage.io/managed-by-location` annotation. Configuration: [`prCreation`](configuration.md#prcreation) and [`scm`](configuration.md#scm). -This needs an SCM provider module with pull request support for the host (e.g. [Bitbucket Server](../../ownership-matcher-backend-module-bitbucket-server/README.md)) and a `writeToken` for it. +This needs an SCM provider module with pull request support for the host (e.g. [Bitbucket Server](../../ownership-matcher-backend-module-bitbucket-server/README.md) or [GitLab](../../ownership-matcher-backend-module-gitlab/README.md)) and a `writeToken` for it (`ownershipMatcher.scm.hosts[].writeToken`). Providers never fall back to the integration credentials for writes. ## PR job diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/configuration.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/configuration.md index dca6567..84cbaed 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/configuration.md +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/configuration.md @@ -196,13 +196,13 @@ How your catalog models people and teams. Also read by the frontend and by other | Key | Default | Description | | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `annotations.userAlias` | unset | User annotation with an alternative login. Commit emails whose local part doesn't match a user name are matched against it. | +| `annotations.userAlias` | unset | User annotation with an alternative login. Commit emails that match neither a user's `spec.profile.email` nor a user name are matched against it by local part. | | `annotations.manager` | unset | User annotation with the manager's `userAlias` value. Required, together with `userAlias`, for levels with `managerChain: true`. | | `teamGroupTypes` | `[team]` | Group `spec.type` values that can own entities. Must not be empty. | ### `scm` -`scm.hosts[]` adds per-host settings to the `integrations.*` entries. `writeToken` is used for catalog-info PRs. Hosts, API URLs and read credentials come from `integrations.*`. +`scm.hosts[]` adds per-host settings to the `integrations.*` entries. `writeToken` is used for catalog-info PRs. Providers never fall back to the integration credentials for writes: without a `writeToken`, PR automation is refused for the host. To reuse the integration's token, point `writeToken` at the same secret (e.g. `${GITLAB_TOKEN}`). Hosts, API URLs and read credentials come from `integrations.*`. ### `prCreation` diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/extending.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/extending.md index 251ef3d..4bed2b0 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/extending.md +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/extending.md @@ -69,7 +69,7 @@ describeScmProviderConformance(gitlabProvider, { fakeServer }); `fakeServer` provides the integration, a `fetch` serving a fake SCM, a sample location with its expected parse, and a hook that makes a file revision stale. The suite covers location parsing, host-restricted `fetch`, idempotent branch and PR creation, `conflict` on a stale revision and reading a PR back. -[Bitbucket Server](../../ownership-matcher-backend-module-bitbucket-server/README.md) is the reference implementation. +[Bitbucket Server](../../ownership-matcher-backend-module-bitbucket-server/README.md) and [GitLab](../../ownership-matcher-backend-module-gitlab/README.md) are reference implementations. ## Email sender diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/proposal-scoring.md b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/proposal-scoring.md index 1ea5fb8..23b4c39 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/proposal-scoring.md +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/docs/proposal-scoring.md @@ -11,7 +11,7 @@ When an entity fails a check, the configured strategies find candidate owner tea | `fallback` | `escalated`: none. `fixed-owner`: the configured `owner` | 0 | | custom | Strategies added by modules through `ownershipProposalStrategiesExtensionPoint` | Set by the strategy | -Commit authors are matched to users by email local part (or the `userAlias` annotation) and then to their teams. Teams that already rejected the entity are skipped. Authors in `contributors` are ignored. +Commit authors are matched to users, then to their teams. A user matches if, in this order, their `spec.profile.email` equals the full commit email (case-insensitive), their name matches the email local part (ignoring any `_` suffix), or their `userAlias` annotation equals the local part. Only users with `spec.memberOf` are considered. Teams that already rejected the entity are skipped. Authors in `contributors` are ignored. ## Combining scores diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.test.ts index 8a524f0..2bfc351 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.test.ts +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.test.ts @@ -33,7 +33,14 @@ function makeConfig( } function makeCatalogService( - users: Array<{ name: string; memberOf?: string[]; sam?: string }> = [], + users: Array<{ + name: string; + memberOf?: string[]; + sam?: string; + profileEmail?: string; + /** Omit `spec.memberOf` entirely. */ + noMembership?: boolean; + }> = [], ): CatalogService { const items = users.map(u => ({ kind: 'User', @@ -41,7 +48,10 @@ function makeCatalogService( name: u.name, ...(u.sam ? { annotations: { [ALIAS_ANNOTATION]: u.sam } } : {}), }, - spec: { memberOf: u.memberOf ?? [] }, + spec: { + ...(u.noMembership ? {} : { memberOf: u.memberOf ?? [] }), + ...(u.profileEmail ? { profile: { email: u.profileEmail } } : {}), + }, })); return { getUserData: jest.fn().mockResolvedValue(items), @@ -275,6 +285,89 @@ describe('ContributorService', () => { expect(await svc.getContributorInfo('nobody01@example.com')).toBeNull(); }); + it('matches the full commit email against spec.profile.email case-insensitively', async () => { + const catalog = makeCatalogService([ + { + name: 'jdoe', + profileEmail: 'Jane.Doe@Example.com', + memberOf: ['group:default/team-a'], + }, + ]); + const svc = new ContributorService( + catalog, + logger, + makeConfig(), + ALIAS_ANNOTATION, + ); + + expect(await svc.getContributorInfo('jane.doe@example.com')).toEqual({ + email: 'jane.doe@example.com', + teams: ['team-a'], + }); + }); + + it('prefers a profile-email match over a name-prefix match on another user', async () => { + const catalog = makeCatalogService([ + { name: 'alice', memberOf: ['group:default/team-name'] }, + { + name: 'a.smith', + profileEmail: 'alice@example.com', + memberOf: ['group:default/team-email'], + }, + ]); + const svc = new ContributorService( + catalog, + logger, + makeConfig(), + ALIAS_ANNOTATION, + ); + + expect( + (await svc.getContributorInfo('alice@example.com'))?.teams, + ).toEqual(['team-email']); + }); + + it('falls back to the name-prefix match when the profile email differs', async () => { + const catalog = makeCatalogService([ + { + name: 'bob', + profileEmail: 'robert@corp.example.com', + memberOf: ['group:default/team-b'], + }, + ]); + const svc = new ContributorService( + catalog, + logger, + makeConfig(), + ALIAS_ANNOTATION, + ); + + expect((await svc.getContributorInfo('bob@example.com'))?.teams).toEqual([ + 'team-b', + ]); + }); + + it('skips a profile-email match without memberOf so a later match still wins', async () => { + const catalog = makeCatalogService([ + { + name: 'ghost', + profileEmail: 'carol@example.com', + noMembership: true, + }, + { name: 'carol', memberOf: ['group:default/team-c'] }, + ]); + const svc = new ContributorService( + catalog, + logger, + makeConfig(), + ALIAS_ANNOTATION, + ); + + expect( + (await svc.getContributorInfo('carol@example.com'))?.teams, + ).toEqual(['team-c']); + }); + it('prefers the name-prefix match over a SAM match on another user', async () => { const catalog = makeCatalogService([ { diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.ts index d652961..811bbff 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.ts +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-backend/src/service/ContributorService.ts @@ -74,20 +74,30 @@ export class ContributorService { const userData = await this.loadUserData(); - // Match on the portion before any '_' suffix in both the email prefix and - // the catalog user name — accommodates common LDAP conventions. Failing - // that, match the whole local part against the user's configured alias + // First, match the full commit email against the user's + // `spec.profile.email` (case-insensitive) — exact and provider-independent + // for anyone who commits with their work address. Failing that, match on + // the portion before any '_' suffix in both the email prefix and the + // catalog user name — accommodates common LDAP conventions. Failing that, + // match the whole local part against the user's configured alias // annotation (case-insensitive: directories store some as e.g. `DoeJ01`), // since many people commit under their alias rather than their name. - const localPart = email.split('@')[0].toLowerCase(); + const emailLower = email.toLowerCase(); + const localPart = emailLower.split('@')[0]; const emailPrefix = localPart.split('_')[0]; - // Require `memberOf` inside each lookup so a name-prefix match without - // memberOf doesn't hide an alias match. + // Require `memberOf` inside each lookup so a match without memberOf + // doesn't hide a later one. const hasMembership = (user: CatalogComponent) => Boolean(user.spec?.memberOf); const aliasAnnotation = this.userAliasAnnotation; const matchingUser = + userData.find( + user => + hasMembership(user) && + typeof user.spec?.profile?.email === 'string' && + user.spec.profile.email.toLowerCase() === emailLower, + ) ?? userData.find( user => hasMembership(user) && diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.test.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.test.ts index ef75412..5a8c386 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.test.ts +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.test.ts @@ -101,6 +101,39 @@ describe('CatalogService', () => { }), ); }); + + it('maps spec.profile.email when present', async () => { + const api = makeCatalogApi([]); + (api.getEntities as jest.Mock).mockResolvedValue({ + items: [ + { + kind: 'User', + metadata: { name: 'jane' }, + spec: { + memberOf: ['group:default/team-a'], + profile: { email: 'jane@example.com', displayName: 'Jane' }, + }, + }, + ], + }); + const svc = new CatalogService(api, logger); + + await expect(svc.getUserData()).resolves.toEqual([ + { + kind: 'User', + metadata: { name: 'jane', annotations: undefined }, + spec: { + memberOf: ['group:default/team-a'], + profile: { email: 'jane@example.com' }, + }, + }, + ]); + expect(api.getEntities).toHaveBeenCalledWith( + expect.objectContaining({ + fields: expect.arrayContaining(['spec.profile.email']), + }), + ); + }); }); describe('getEntityByRef', () => { diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.ts index 9de120e..e1d557d 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.ts +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/catalog/CatalogService.ts @@ -242,23 +242,36 @@ export class CatalogService implements CatalogServiceExtensions { } } - /** Fetches all User entities to resolve email → team membership. */ + /** Fetches all User entities (name, annotations, memberOf, profile email) to resolve email → team membership. */ async getUserData(): Promise { try { const response = await this.catalogClient.getEntities({ filter: { kind: 'User' }, - fields: ['metadata.name', 'metadata.annotations', 'spec.memberOf'], + fields: [ + 'metadata.name', + 'metadata.annotations', + 'spec.memberOf', + 'spec.profile.email', + ], + }); + return response.items.map(e => { + const email = (e as any).spec?.profile?.email; + return { + kind: e.kind, + metadata: { + name: e.metadata.name, + annotations: e.metadata.annotations as + | Record + | undefined, + }, + spec: { + memberOf: (e as any).spec?.memberOf, + ...(typeof email === 'string' && email + ? { profile: { email } } + : {}), + }, + }; }); - return response.items.map(e => ({ - kind: e.kind, - metadata: { - name: e.metadata.name, - annotations: e.metadata.annotations as - | Record - | undefined, - }, - spec: { memberOf: (e as any).spec?.memberOf }, - })); } catch (error) { this.logger.error( `CatalogService.getUserData failed: ${ diff --git a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/types.ts b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/types.ts index 1b388bf..c8fb0f9 100644 --- a/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/types.ts +++ b/workspaces/ownership-matcher/plugins/ownership-matcher-node/src/types.ts @@ -33,7 +33,7 @@ export interface CatalogComponent { domain?: string; lifecycle?: string; type?: string; - profile?: { title?: string; [key: string]: unknown }; + profile?: { title?: string; email?: string; [key: string]: unknown }; }; } diff --git a/yarn.lock b/yarn.lock index ead7c96..8b8c006 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7390,6 +7390,20 @@ __metadata: languageName: unknown linkType: soft +"@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab@workspace:workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab": + version: 0.0.0-use.local + resolution: "@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-gitlab@workspace:workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-gitlab" + dependencies: + "@backstage/backend-plugin-api": "npm:^1.10.1" + "@backstage/backend-test-utils": "npm:^1.11.7" + "@backstage/cli": "npm:^0.36.6" + "@backstage/config": "npm:^1.3.9" + "@backstage/integration": "npm:^2.1.2" + "@stepstone-tech/backstage-plugin-ownership-matcher-backend": "workspace:^" + "@stepstone-tech/backstage-plugin-ownership-matcher-node": "workspace:^" + languageName: unknown + linkType: soft + "@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-msgraph-email@workspace:workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-msgraph-email": version: 0.0.0-use.local resolution: "@stepstone-tech/backstage-plugin-ownership-matcher-backend-module-msgraph-email@workspace:workspaces/ownership-matcher/plugins/ownership-matcher-backend-module-msgraph-email"