glab-release-notes 0.1.0__tar.gz

glab_release_notes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladimir Voronov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glab_release_notes-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: glab-release-notes
+Version: 0.1.0
+Summary: GitLab release notes from merged MRs: validate labels and quote, append entries, and promote them under a version in CI.
+Keywords: gitlab,release-notes,changelog,ci,merge-request
+Author: Vladimir Voronov
+Author-email: Vladimir Voronov <vvoronov@mwnts.ru>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/redb0/glab-release-notes
+Project-URL: Repository, https://github.com/redb0/glab-release-notes
+Project-URL: Issues, https://github.com/redb0/glab-release-notes/issues
+Project-URL: Changelog, https://github.com/redb0/glab-release-notes/releases
+Description-Content-Type: text/markdown
+
+# Glab Release Notes
+
+Automatically add the changes from each merged merge request to human-readable release notes in a file.
+
+This is a GitLab-oriented take on [latest-changes](https://github.com/tiangolo/latest-changes): a small, dependency-free CLI that runs in your GitLab CI and keeps a `release-notes.md` up to date as merge requests get merged.
+
+Unlike tools that scrape `git log` or conventional-commit messages, it reads the data **from the merge request itself**:
+
+* a **label** decides which section the entry lands in,
+* a **one-line quote** (`> …`) in the MR description is the entry text,
+* a **ticket key** in the source-branch name (e.g. `FMT-1110`) becomes an optional Jira link.
+
+So the person writing the MR writes the one sentence that matters, and CI takes care of the formatting, links, author, and ordering.
+
+## How it works
+
+A release notes file is plain Markdown with an `## Latest Changes` block at the top and versioned blocks below it:
+
+```Markdown
+# Release notes
+
+## Latest Changes
+
+### Features
+
+### Fixes
+
+## 0.8.1
+
+### Fixes {#fix_0.8.1}
+
+* 🐛 Fixed a crash on empty input ([#35](https://gitlab.example/your/project/-/merge_requests/35)) by [@alice](https://gitlab.example/alice)
+```
+
+After a merge request is merged, the `append` command finds the `## Latest Changes` block and adds a new list item to the section chosen by the MR's label:
+
+> ## Latest Changes
+>
+> ### Features
+>
+> * ✨ Add support for detailed gRPC errors ([#123](https://gitlab.example/your/project/-/merge_requests/123), [FMT-1110](https://jira.example/browse/FMT-1110)) by [@bob](https://gitlab.example/bob)
+
+The entry is built from:
+
+* the **label** → section and emoji (see [Using labels](#using-labels)),
+* the **last non-empty `> …` quote** in the MR description → the entry text,
+* the **ticket key** parsed from the source branch name → a Jira link (only when a `--jira-base` is given),
+* the MR **author** and **URL** → trailing `by [@author](…)`.
+
+The entry is prepended to the top of the section so the newest change reads first. Because the notes are just a file in your repo, you can later tweak, reorder, or extend any entry by hand.
+
+## Using labels
+
+A merge request is routed to a section by its labels. The built-in default mapping is:
+
+| Label       | Section         | Emoji |
+| ----------- | --------------- | ----- |
+| `feature`   | `Features`      | ✨    |
+| `bug`       | `Fixes`         | 🐛    |
+| `docs`      | `Documentation` | 📝    |
+| `ci`        | `CI`            | 👷    |
+
+Labels that are never recorded into the notes:
+
+* `release`, `refactor`, `test`, `chore`, `style`
+
+Rules:
+
+* A merge request must carry **either** a section label **or** a skip label.
+* A **skip label wins** if both a section label and a skip label are present.
+* With several section labels, the first one in the configured order wins.
+* A section label **requires** a `> …` quote in the description; a skip label does not.
+
+`Features` and `Fixes` always exist (even when empty). The other sections appear only once they have at least one entry.
+
+## Getting started
+
+1. **Add the notes file** (if you don't have one), e.g. `docs/release-notes.md`:
+
+   ```Markdown
+   # Release notes
+
+   ## Latest Changes
+
+   ### Features
+
+   ### Fixes
+   ```
+
+2. **Add a merge-request template** that asks authors to set a label and write a one-line quote. A minimal `Default.md`:
+
+   ```Markdown
+   /label ~feature
+
+   ## Release notes
+
+   One line in a quote. No emojis and no links — CI adds those after the merge.
+
+   >
+   ```
+
+3. **Add the CI jobs** (see [CI wiring](#ci-wiring)).
+
+That's enough for `validate` and `append` to work. `promote` is what your release job calls.
+
+## Commands
+
+```
+glab-release-notes [--config PATH] [--file PATH] <command>
+```
+
+* `validate` — a gate for the MR pipeline. Fails the pipeline when the MR has neither a section label nor a skip label, or has a section label but no `> …` quote.
+* `append` — after a merge, appends the entry to the `## Latest Changes` block and pushes a `chore(notes): add entry for MR !<iid>` commit. It retries on a push race and is idempotent: an already-recorded MR is skipped.
+* `promote` — moves the non-empty sections of `## Latest Changes` under a new `## <version>` heading with anchors, then empties the block back to the always-kept sections. `--version` is required; `--no-push` rewrites the file only so your release process can own the commit.
+
+## CI wiring
+
+The tool talks to the GitLab API using CI variables, so it is bound to whichever project's pipeline runs it:
+
+* `CI_API_V4_URL`, `CI_PROJECT_ID`, `GITLAB_API_TOKEN` — API endpoint and auth;
+* `CI_MERGE_REQUEST_IID` — used by `validate`;
+* `CI_COMMIT_SHA` — used by `append` to find the MR of the current commit.
+
+A typical `.gitlab-ci.yml`:
+
+```yaml
+validate-release-notes:
+  stage: linter
+  script:
+    - uv run glab-release-notes validate
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+
+append-release-notes:
+  stage: linter
+  variables:
+    GIT_DEPTH: 0
+  before_script:
+    - !reference [.base_git_pre_settings, script]   # git credentials for the push
+  script:
+    - uv run glab-release-notes append --jira-base https://jira.example/browse
+  rules:
+    - if: $CI_COMMIT_TAG || $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: never
+    - if: '$CI_COMMIT_MESSAGE =~ /^chore\(notes\)/'
+      when: never
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+```
+
+The `chore(notes)` rule prevents the job from re-running on its own commits, and `GIT_DEPTH: 0` gives `append` a full history. The `before_script` must configure git with credentials able to push to the target branch (see [Pushing to a protected branch](#pushing-to-a-protected-branch)).
+
+### Promoting on release
+
+Call `promote` in your release job, right before (and, with `--no-push`, folded into) the release commit:
+
+```yaml
+    - uv run glab-release-notes promote --version "${version}" --no-push
+```
+
+## Existing MRs — running manually
+
+`append` resolves the MR from `CI_COMMIT_SHA` by default. To record a specific merge request by hand — for example one that was merged before you added this — run `append` on the target branch with the `MR_IID` variable set:
+
+```
+MR_IID=123 uv run glab-release-notes append --jira-base https://jira.example/browse
+```
+
+This is also the escape hatch for any MR the automatic run skipped.
+
+## Configuration
+
+The wording of the release notes — the file, the `Latest Changes` header, the sections, the labels, and the skip labels — is configurable, in the same spirit as [latest-changes](https://github.com/tiangolo/latest-changes). Put a `release-notes.toml` in the repo root and it is picked up automatically; pass `--config PATH` to point at a different file. Without a config file, the built-in defaults from [Using labels](#using-labels) apply.
+
+Precedence: CLI flags (`--file`) > config file > built-in defaults.
+
+```toml
+# release-notes.toml
+file = "docs/release-notes.md"        # the notes file (CLI --file wins)
+unreleased_header = "## Latest Changes"
+section_prefix = "### "
+skip_labels = ["release", "refactor", "test", "chore", "style"]
+always_keep = ["Features", "Fixes"]
+
+[[section]]
+label = "feature"
+header = "Features"
+emoji = "✨"
+anchor_prefix = "feat"
+
+[[section]]
+label = "bug"
+header = "Fixes"
+emoji = "🐛"
+anchor_prefix = "fix"
+
+[[section]]
+label = "docs"
+header = "Documentation"
+emoji = "📝"
+anchor_prefix = "docs"
+
+[[section]]
+label = "ci"
+header = "CI"
+emoji = "👷"
+anchor_prefix = "ci"
+```
+
+Keys:
+
+* `file` — the notes file to update. Defaults to `docs/release-notes.md`.
+* `unreleased_header` — the header of the accumulating block. Defaults to `## Latest Changes`.
+* `section_prefix` — the prefix of the section headers inside the block. Defaults to `### `.
+* `skip_labels` — labels that are never recorded. A skip label also wins over a section label.
+* `always_keep` — section headers that are always rendered, even when empty. Defaults to `["Features", "Fixes"]`; use `[]` to render a section only once it has an entry (the latest-changes behavior).
+* `[[section]]` — one table per section:
+    * `label` (required) — the GitLab label that routes an MR to this section.
+    * `header` (required) — the section header text.
+    * `emoji` (optional) — the emoji prefixed to entries in this section. Omit it for a plain entry.
+    * `anchor_prefix` (optional) — the anchor prefix used when promoting, e.g. `{#feat_1.0.0}`. Defaults to the label.
+
+The order of `[[section]]` tables matters in both directions: it is the display order of the sections, and the first matching label wins when an MR carries several section labels.
+
+The entry line format itself is fixed: `* <emoji> <text> (links) by <author>`. It is not a template.
+
+## Pushing to a protected branch
+
+`append` and `promote` (without `--no-push`) `git commit` and `git push` the updated notes. If your target branch is protected against direct pushes, the CI job must be running with credentials that can push to it.
+
+In GitLab that usually means one of:
+
+* the job runs as a user/role allowed to push to the branch, or
+* you pass a token to the git setup (the `!reference [.base_git_pre_settings, script]` pattern above) that can push.
+
+The commits are attributed to the CI identity, not to any individual author.
+
+## Development
+
+```
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy glab_release_notes tests
+uv run pytest
+```
+
+Releases are managed with [commitizen](https://github.com/commitizen/commitizen): `uv run cz bump` updates the version and `CHANGELOG.md` and tags the commit. A GitHub Release on that tag publishes the package to PyPI via trusted publishing (`.github/workflows/publish.yaml`).
+
+## License
+
+This project is licensed under the terms of the MIT license.

glab_release_notes-0.1.0/README.md

@@ -0,0 +1,251 @@
+# Glab Release Notes
+
+Automatically add the changes from each merged merge request to human-readable release notes in a file.
+
+This is a GitLab-oriented take on [latest-changes](https://github.com/tiangolo/latest-changes): a small, dependency-free CLI that runs in your GitLab CI and keeps a `release-notes.md` up to date as merge requests get merged.
+
+Unlike tools that scrape `git log` or conventional-commit messages, it reads the data **from the merge request itself**:
+
+* a **label** decides which section the entry lands in,
+* a **one-line quote** (`> …`) in the MR description is the entry text,
+* a **ticket key** in the source-branch name (e.g. `FMT-1110`) becomes an optional Jira link.
+
+So the person writing the MR writes the one sentence that matters, and CI takes care of the formatting, links, author, and ordering.
+
+## How it works
+
+A release notes file is plain Markdown with an `## Latest Changes` block at the top and versioned blocks below it:
+
+```Markdown
+# Release notes
+
+## Latest Changes
+
+### Features
+
+### Fixes
+
+## 0.8.1
+
+### Fixes {#fix_0.8.1}
+
+* 🐛 Fixed a crash on empty input ([#35](https://gitlab.example/your/project/-/merge_requests/35)) by [@alice](https://gitlab.example/alice)
+```
+
+After a merge request is merged, the `append` command finds the `## Latest Changes` block and adds a new list item to the section chosen by the MR's label:
+
+> ## Latest Changes
+>
+> ### Features
+>
+> * ✨ Add support for detailed gRPC errors ([#123](https://gitlab.example/your/project/-/merge_requests/123), [FMT-1110](https://jira.example/browse/FMT-1110)) by [@bob](https://gitlab.example/bob)
+
+The entry is built from:
+
+* the **label** → section and emoji (see [Using labels](#using-labels)),
+* the **last non-empty `> …` quote** in the MR description → the entry text,
+* the **ticket key** parsed from the source branch name → a Jira link (only when a `--jira-base` is given),
+* the MR **author** and **URL** → trailing `by [@author](…)`.
+
+The entry is prepended to the top of the section so the newest change reads first. Because the notes are just a file in your repo, you can later tweak, reorder, or extend any entry by hand.
+
+## Using labels
+
+A merge request is routed to a section by its labels. The built-in default mapping is:
+
+| Label       | Section         | Emoji |
+| ----------- | --------------- | ----- |
+| `feature`   | `Features`      | ✨    |
+| `bug`       | `Fixes`         | 🐛    |
+| `docs`      | `Documentation` | 📝    |
+| `ci`        | `CI`            | 👷    |
+
+Labels that are never recorded into the notes:
+
+* `release`, `refactor`, `test`, `chore`, `style`
+
+Rules:
+
+* A merge request must carry **either** a section label **or** a skip label.
+* A **skip label wins** if both a section label and a skip label are present.
+* With several section labels, the first one in the configured order wins.
+* A section label **requires** a `> …` quote in the description; a skip label does not.
+
+`Features` and `Fixes` always exist (even when empty). The other sections appear only once they have at least one entry.
+
+## Getting started
+
+1. **Add the notes file** (if you don't have one), e.g. `docs/release-notes.md`:
+
+   ```Markdown
+   # Release notes
+
+   ## Latest Changes
+
+   ### Features
+
+   ### Fixes
+   ```
+
+2. **Add a merge-request template** that asks authors to set a label and write a one-line quote. A minimal `Default.md`:
+
+   ```Markdown
+   /label ~feature
+
+   ## Release notes
+
+   One line in a quote. No emojis and no links — CI adds those after the merge.
+
+   >
+   ```
+
+3. **Add the CI jobs** (see [CI wiring](#ci-wiring)).
+
+That's enough for `validate` and `append` to work. `promote` is what your release job calls.
+
+## Commands
+
+```
+glab-release-notes [--config PATH] [--file PATH] <command>
+```
+
+* `validate` — a gate for the MR pipeline. Fails the pipeline when the MR has neither a section label nor a skip label, or has a section label but no `> …` quote.
+* `append` — after a merge, appends the entry to the `## Latest Changes` block and pushes a `chore(notes): add entry for MR !<iid>` commit. It retries on a push race and is idempotent: an already-recorded MR is skipped.
+* `promote` — moves the non-empty sections of `## Latest Changes` under a new `## <version>` heading with anchors, then empties the block back to the always-kept sections. `--version` is required; `--no-push` rewrites the file only so your release process can own the commit.
+
+## CI wiring
+
+The tool talks to the GitLab API using CI variables, so it is bound to whichever project's pipeline runs it:
+
+* `CI_API_V4_URL`, `CI_PROJECT_ID`, `GITLAB_API_TOKEN` — API endpoint and auth;
+* `CI_MERGE_REQUEST_IID` — used by `validate`;
+* `CI_COMMIT_SHA` — used by `append` to find the MR of the current commit.
+
+A typical `.gitlab-ci.yml`:
+
+```yaml
+validate-release-notes:
+  stage: linter
+  script:
+    - uv run glab-release-notes validate
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+
+append-release-notes:
+  stage: linter
+  variables:
+    GIT_DEPTH: 0
+  before_script:
+    - !reference [.base_git_pre_settings, script]   # git credentials for the push
+  script:
+    - uv run glab-release-notes append --jira-base https://jira.example/browse
+  rules:
+    - if: $CI_COMMIT_TAG || $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: never
+    - if: '$CI_COMMIT_MESSAGE =~ /^chore\(notes\)/'
+      when: never
+    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+```
+
+The `chore(notes)` rule prevents the job from re-running on its own commits, and `GIT_DEPTH: 0` gives `append` a full history. The `before_script` must configure git with credentials able to push to the target branch (see [Pushing to a protected branch](#pushing-to-a-protected-branch)).
+
+### Promoting on release
+
+Call `promote` in your release job, right before (and, with `--no-push`, folded into) the release commit:
+
+```yaml
+    - uv run glab-release-notes promote --version "${version}" --no-push
+```
+
+## Existing MRs — running manually
+
+`append` resolves the MR from `CI_COMMIT_SHA` by default. To record a specific merge request by hand — for example one that was merged before you added this — run `append` on the target branch with the `MR_IID` variable set:
+
+```
+MR_IID=123 uv run glab-release-notes append --jira-base https://jira.example/browse
+```
+
+This is also the escape hatch for any MR the automatic run skipped.
+
+## Configuration
+
+The wording of the release notes — the file, the `Latest Changes` header, the sections, the labels, and the skip labels — is configurable, in the same spirit as [latest-changes](https://github.com/tiangolo/latest-changes). Put a `release-notes.toml` in the repo root and it is picked up automatically; pass `--config PATH` to point at a different file. Without a config file, the built-in defaults from [Using labels](#using-labels) apply.
+
+Precedence: CLI flags (`--file`) > config file > built-in defaults.
+
+```toml
+# release-notes.toml
+file = "docs/release-notes.md"        # the notes file (CLI --file wins)
+unreleased_header = "## Latest Changes"
+section_prefix = "### "
+skip_labels = ["release", "refactor", "test", "chore", "style"]
+always_keep = ["Features", "Fixes"]
+
+[[section]]
+label = "feature"
+header = "Features"
+emoji = "✨"
+anchor_prefix = "feat"
+
+[[section]]
+label = "bug"
+header = "Fixes"
+emoji = "🐛"
+anchor_prefix = "fix"
+
+[[section]]
+label = "docs"
+header = "Documentation"
+emoji = "📝"
+anchor_prefix = "docs"
+
+[[section]]
+label = "ci"
+header = "CI"
+emoji = "👷"
+anchor_prefix = "ci"
+```
+
+Keys:
+
+* `file` — the notes file to update. Defaults to `docs/release-notes.md`.
+* `unreleased_header` — the header of the accumulating block. Defaults to `## Latest Changes`.
+* `section_prefix` — the prefix of the section headers inside the block. Defaults to `### `.
+* `skip_labels` — labels that are never recorded. A skip label also wins over a section label.
+* `always_keep` — section headers that are always rendered, even when empty. Defaults to `["Features", "Fixes"]`; use `[]` to render a section only once it has an entry (the latest-changes behavior).
+* `[[section]]` — one table per section:
+    * `label` (required) — the GitLab label that routes an MR to this section.
+    * `header` (required) — the section header text.
+    * `emoji` (optional) — the emoji prefixed to entries in this section. Omit it for a plain entry.
+    * `anchor_prefix` (optional) — the anchor prefix used when promoting, e.g. `{#feat_1.0.0}`. Defaults to the label.
+
+The order of `[[section]]` tables matters in both directions: it is the display order of the sections, and the first matching label wins when an MR carries several section labels.
+
+The entry line format itself is fixed: `* <emoji> <text> (links) by <author>`. It is not a template.
+
+## Pushing to a protected branch
+
+`append` and `promote` (without `--no-push`) `git commit` and `git push` the updated notes. If your target branch is protected against direct pushes, the CI job must be running with credentials that can push to it.
+
+In GitLab that usually means one of:
+
+* the job runs as a user/role allowed to push to the branch, or
+* you pass a token to the git setup (the `!reference [.base_git_pre_settings, script]` pattern above) that can push.
+
+The commits are attributed to the CI identity, not to any individual author.
+
+## Development
+
+```
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy glab_release_notes tests
+uv run pytest
+```
+
+Releases are managed with [commitizen](https://github.com/commitizen/commitizen): `uv run cz bump` updates the version and `CHANGELOG.md` and tags the commit. A GitHub Release on that tag publishes the package to PyPI via trusted publishing (`.github/workflows/publish.yaml`).
+
+## License
+
+This project is licensed under the terms of the MIT license.

glab_release_notes-0.1.0/glab_release_notes/__init__.py

@@ -0,0 +1,32 @@
+"""Release notes for GitLab projects, generated from merged merge requests."""
+
+from glab_release_notes.config import NotesConfig, default_config, load_config
+from glab_release_notes.edit import append_note, promote_notes
+from glab_release_notes.models import LabelDecision, MergeRequest, ReleaseNotesError
+from glab_release_notes.parse import (
+    already_recorded,
+    classify,
+    parse_quote,
+    parse_ticket,
+    validate_record,
+)
+from glab_release_notes.payload import merge_request_from_payload
+from glab_release_notes.render import format_entry
+
+__all__ = (
+    "LabelDecision",
+    "MergeRequest",
+    "NotesConfig",
+    "ReleaseNotesError",
+    "already_recorded",
+    "append_note",
+    "classify",
+    "default_config",
+    "format_entry",
+    "load_config",
+    "merge_request_from_payload",
+    "parse_quote",
+    "parse_ticket",
+    "promote_notes",
+    "validate_record",
+)

glab_release_notes-0.1.0/glab_release_notes/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point: ``python -m glab_release_notes``."""
+
+from glab_release_notes.cli import main
+
+if __name__ == "__main__":
+    main()

glab_release_notes-0.1.0/glab_release_notes/api.py

@@ -0,0 +1,40 @@
+"""Fetch merge requests from the GitLab API."""
+
+from urllib.parse import quote
+
+from glab_release_notes.http import Payload, gitlab_json, payload_list
+from glab_release_notes.models import MergeRequest, ReleaseNotesError
+from glab_release_notes.payload import merge_request_from_payload
+
+
+def fetch_mr(iid: int) -> MergeRequest:
+    """Load a merge request by iid."""
+    raw = gitlab_json(f"merge_requests/{iid}")
+    if not isinstance(raw, dict):
+        msg = f"Invalid GitLab response for MR !{iid}"
+        raise ReleaseNotesError(msg)
+    return merge_request_from_payload(raw)
+
+
+def _first_or_none(payloads: list[Payload]) -> Payload | None:
+    if payloads:
+        return payloads[0]
+    return None
+
+
+def _pick_payload(payloads: list[Payload]) -> Payload | None:
+    merged = [payload for payload in payloads if payload.get("state") == "merged"]
+    chosen = _first_or_none(merged)
+    if chosen is not None:
+        return chosen
+    return _first_or_none(payloads)
+
+
+def fetch_mr_for_commit(sha: str) -> MergeRequest | None:
+    """Find the merged merge request for a commit SHA."""
+    encoded = quote(sha, safe="")
+    path = f"repository/commits/{encoded}/merge_requests"
+    chosen = _pick_payload(payload_list(gitlab_json(path)))
+    if chosen is None:
+        return None
+    return merge_request_from_payload(chosen)