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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/gitlab-scm-provider.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 6 additions & 0 deletions .changeset/profile-email-contributors.md
Original file line number Diff line number Diff line change
@@ -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`.
3 changes: 2 additions & 1 deletion workspaces/ownership-matcher/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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=<entityRef>`, which is the quickest way to check the lead-only views as somebody else — for example `user:default/alice`, who leads nothing.

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

Expand Down
7 changes: 6 additions & 1 deletion workspaces/ownership-matcher/packages/backend/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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();
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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);
Original file line number Diff line number Diff line change
@@ -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 `<baseUrl>/<group>[/<subgroup>...]/<project>/-/blob/<ref>/<path>`. `<ref>` 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`.
Original file line number Diff line number Diff line change
@@ -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"
}
}
Loading
Loading