gitlab-mr-commenter 2.0.1__tar.gz

gitlab_mr_commenter-2.0.1/.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Verify the package installs and the CLI entry point is present.
+  smoke-test:
+    name: Smoke test
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install from wheel
+        run: |
+          uv venv
+          uv pip install dist/*.whl
+
+      - name: Verify CLI entry point
+        run: uv run gitlab-mr-commenter --help
+
+      - name: Verify library import
+        run: uv run python -c "from gitlab_mr_commenter import MRCommenter, post_comment; print('OK')"
+
+  publish:
+    name: Publish to PyPI
+    needs: [build, smoke-test]
+    runs-on: ubuntu-latest
+
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gitlab-mr-commenter
+
+    # Trusted Publishing — no API token stored in GitHub secrets.
+    # Set this up once at https://pypi.org/manage/project/gitlab-mr-commenter/settings/publishing/
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

gitlab_mr_commenter-2.0.1/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Semantic release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Use a token that can push to protected branches and trigger
+          # downstream workflows (the default GITHUB_TOKEN cannot).
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install python-semantic-release
+        run: uv tool install python-semantic-release
+
+      - name: Run semantic-release
+        run: semantic-release version --push
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}

gitlab_mr_commenter-2.0.1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v2.0.1 (2026-02-19)
+
+### Bug Fixes
+
+- **ci**: Use uv venv instead of --system for smoke-test
+  ([`c0a8317`](https://github.com/gianklug/gitlab-mr-commenter/commit/c0a831799170348966dc6985e055f3093940399a))
+
+
+## v2.0.0 (2026-02-19)
+
+### Continuous Integration
+
+- Add semantic release and fix smoke-test wheel install
+  ([`3b96b0a`](https://github.com/gianklug/gitlab-mr-commenter/commit/3b96b0a139f6acd36d3ce571f8d8cab188cba41b))
+
+### Features
+
+- Switch to semrel
+  ([`d866c23`](https://github.com/gianklug/gitlab-mr-commenter/commit/d866c23dcef0e94d59ed2f831d5948ff53a41f6e))
+
+
+## v1.0.0 (2026-02-19)
+
+- Initial Release

gitlab_mr_commenter-2.0.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: gitlab-mr-commenter
+Version: 2.0.1
+Summary: Post and idempotently update comments on GitLab merge requests
+Author-email: Gian Klug <gk@gk.wtf>
+Requires-Python: >=3.9
+Requires-Dist: python-gitlab>=8.0

gitlab_mr_commenter-2.0.1/README.md

@@ -0,0 +1,183 @@
+# gitlab-mr-commenter
+
+Post and **idempotently update** comments on GitLab merge requests.
+
+Re-running with the same `comment_id` updates the existing note in place rather
+than creating a duplicate — useful for plan/apply pipelines where you want a
+single, always-current comment per environment.
+
+Inspired by the `mr-commenter` sub-command in
+[`gitlab-tofu-ctl`](https://gitlab.com/components/opentofu), reimplemented as a
+standalone Python package with both a library API and a CLI.
+
+---
+
+## Installation
+
+```bash
+# Add to a project
+uv add gitlab-mr-commenter
+
+# Run without installing (ephemeral)
+uvx gitlab-mr-commenter --help
+
+# pip also works
+pip install gitlab-mr-commenter
+```
+
+Python 3.9+ is required. The only dependency is
+[`python-gitlab`](https://python-gitlab.readthedocs.io/) ≥ 8.0.
+
+---
+
+## Quick start
+
+### CLI
+
+```bash
+# Content is read from stdin; IDs and token are read from CI environment variables.
+echo "## Plan: no changes" | gitlab-mr-commenter plan-production
+
+# Explicit flags override env vars.
+echo "## Plan: no changes" | gitlab-mr-commenter \
+  --project-id 123 \
+  --mr-iid 45 \
+  --token "$GITLAB_TOKEN" \
+  --api-url "https://gitlab.com/api/v4" \
+  plan-production
+```
+
+### Python
+
+```python
+from gitlab_mr_commenter import MRCommenter
+
+commenter = MRCommenter()          # reads token + URL from env
+commenter.post(
+    project_id=123,
+    mr_iid=45,
+    comment_id="plan-production",
+    content="## Plan\n\nNo changes.",
+)
+```
+
+One-shot convenience function:
+
+```python
+from gitlab_mr_commenter import post_comment
+
+post_comment(123, 45, "plan-production", "## Plan\n\nNo changes.")
+```
+
+---
+
+## Configuration
+
+All configuration can be supplied either as keyword arguments (library) / CLI
+flags, or via environment variables. Environment variables are the natural
+choice in CI pipelines.
+
+| Environment variable | CLI flag | Description |
+|---|---|---|
+| `GITLAB_MR_PLAN_TOKEN` | `--token` | GitLab API token (preferred) |
+| `GITLAB_TOKEN` | `--token` | GitLab API token (fallback) |
+| `CI_API_V4_URL` | `--api-url` | GitLab API base URL, e.g. `https://gitlab.com/api/v4` |
+| `CI_PROJECT_ID` | `--project-id` | Numeric project ID |
+| `CI_MERGE_REQUEST_IID` | `--mr-iid` | MR internal (project-scoped) ID |
+
+> **Token scopes** — the token needs at least the `api` scope (or
+> `write_repository` for project tokens). In GitLab CI, a
+> [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html)
+> with **Developer** role and `api` scope is sufficient.
+
+---
+
+## How it works
+
+Each managed comment has a hidden HTML marker appended to its body:
+
+```
+<!-- gitlab-mr-commenter id="plan-production" -->
+```
+
+On every run the tool paginates through all notes on the MR looking for this
+marker. If found, the note is updated in place. If not found, a new note is
+created. The marker format is compatible with `gitlab-tofu-ctl mr-commenter`
+so both tools can coexist on the same MR.
+
+---
+
+## CLI reference
+
+```
+usage: gitlab-mr-commenter [-h] [--project-id ID] [--mr-iid IID]
+                           [--token TOKEN] [--api-url URL]
+                           COMMENT_ID
+
+positional arguments:
+  COMMENT_ID         Unique name for this comment slot, e.g. 'plan-production'.
+                     A second run with the same value updates the existing comment.
+
+options:
+  -h, --help         show this help message and exit
+  --project-id ID    GitLab project ID. Defaults to $CI_PROJECT_ID.
+  --mr-iid IID       MR internal ID. Defaults to $CI_MERGE_REQUEST_IID.
+  --token TOKEN      GitLab API token. Defaults to $GITLAB_MR_PLAN_TOKEN
+                     or $GITLAB_TOKEN.
+  --api-url URL      GitLab API base URL. Defaults to $CI_API_V4_URL.
+```
+
+---
+
+## Development setup
+
+```bash
+git clone https://github.com/your-org/gitlab-mr-commenter
+cd gitlab-mr-commenter
+
+# Install dependencies (creates .venv automatically)
+uv sync
+
+# Run the CLI
+uv run gitlab-mr-commenter --help
+```
+
+### Running the CLI locally against a real MR
+
+```bash
+export GITLAB_MR_PLAN_TOKEN="glpat-xxxxxxxxxxxx"
+export CI_API_V4_URL="https://gitlab.com/api/v4"
+export CI_PROJECT_ID="12345678"
+export CI_MERGE_REQUEST_IID="42"
+
+echo "## Test comment $(date)" | uv run gitlab-mr-commenter test-local
+```
+
+---
+
+## Publishing
+
+Releases are published to [PyPI](https://pypi.org/project/gitlab-mr-commenter/)
+automatically when a version tag is pushed (see `.github/workflows/publish.yml`).
+The workflow uses [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)
+so no API token needs to be stored in GitHub secrets — set it up once on PyPI's
+side under your project's Publishing settings.
+
+```bash
+# Bump the version in pyproject.toml, then:
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+To publish manually:
+
+```bash
+uv build
+uv publish
+```
+
+---
+
+## License
+
+MIT

gitlab_mr_commenter-2.0.1/examples/gitlab-ci.yml

@@ -0,0 +1,34 @@
+# Example: post a comment on a GitLab MR using gitlab-mr-commenter.
+#
+# Prerequisites
+# -------------
+# 1. Create a project access token (Developer role, `api` scope).
+# 2. Add it as a masked CI/CD variable named GITLAB_MR_PLAN_TOKEN.
+#
+# The variables CI_PROJECT_ID, CI_MERGE_REQUEST_IID, and CI_API_V4_URL are
+# provided automatically by GitLab in merge-request pipelines.
+
+stages:
+  - comment
+
+post-mr-comment:
+  stage: comment
+  image: python:3.12-slim
+  rules:
+    # Only run in merge-request pipelines so CI_MERGE_REQUEST_IID is set.
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - pip install uv
+
+    # Run whatever command you like and capture its output.
+    - OUTPUT=$(date -u)
+
+    # Pipe the output into gitlab-mr-commenter.
+    # Re-running this job updates the same comment rather than creating a new one.
+    # CI_PROJECT_ID, CI_MERGE_REQUEST_IID, and CI_API_V4_URL are picked up automatically.
+    - |
+      cat <<EOF | uvx gitlab-mr-commenter
+      ## Pipeline info
+
+      Triggered by job [#${CI_JOB_ID}](${CI_JOB_URL}) at ${OUTPUT}.
+      EOF

gitlab_mr_commenter-2.0.1/examples/python-script.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Example: call gitlab-mr-commenter from a Python script.
+
+Run (env vars must be set, see README):
+
+    python examples/python-script.py
+"""
+
+import os
+import subprocess
+from gitlab_mr_commenter import MRCommenter
+
+output = subprocess.check_output(["date", "-u"], text=True).strip()
+
+content = f"""\
+## Pipeline info
+
+Triggered at {output} by job [{os.environ.get('CI_JOB_ID', 'local')}]({os.environ.get('CI_JOB_URL', '')})."""
+
+commenter = MRCommenter()  # token + api_url from env
+commenter.post(
+    project_id=int(os.environ["CI_PROJECT_ID"]),
+    mr_iid=int(os.environ["CI_MERGE_REQUEST_IID"]),
+    comment_id="my-comment-slot",
+    content=content,
+)

gitlab_mr_commenter-2.0.1/gitlab_mr_commenter/__init__.py

@@ -0,0 +1,190 @@
+"""gitlab-mr-commenter: post and idempotently update comments on GitLab MRs.
+
+Each comment slot is identified by a hidden HTML marker embedded at the end
+of the comment body.  Re-running with the same ``comment_id`` updates the
+existing comment rather than creating a duplicate.
+
+Typical CI usage
+----------------
+The following environment variables are read automatically when the
+corresponding keyword argument is omitted:
+
+* ``GITLAB_MR_PLAN_TOKEN`` (preferred) or ``GITLAB_TOKEN`` — API token
+* ``CI_API_V4_URL`` — GitLab API base URL
+* ``CI_PROJECT_ID`` — project ID
+* ``CI_MERGE_REQUEST_IID`` — MR internal ID (project-scoped, visible in URLs)
+
+Quick start
+-----------
+As a library::
+
+    from gitlab_mr_commenter import MRCommenter
+
+    commenter = MRCommenter()          # reads token + URL from env
+    commenter.post("## Plan\\n\\nNo changes.")  # project_id/mr_iid from env
+
+    # or explicitly:
+    commenter.post(
+        content="## Plan\\n\\nNo changes.",
+        project_id=123,
+        mr_iid=45,
+        comment_id="plan-production",
+    )
+
+As a one-shot function::
+
+    from gitlab_mr_commenter import post_comment
+
+    post_comment("## Plan\\n\\nNo changes.")  # all from env
+    post_comment("## Plan\\n\\nNo changes.", project_id=123, mr_iid=45, comment_id="plan-production")
+
+From the command line::
+
+    echo "## Plan" | gitlab-mr-commenter plan-production
+    echo "## Plan" | gitlab-mr-commenter --project-id 123 --mr-iid 45 plan-production
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+import gitlab
+
+__all__ = ["COMMENT_IDENTIFIER", "MRCommenter", "post_comment"]
+
+# Hidden HTML marker embedded at the end of every managed comment.
+# Matches the Go reference: `<!-- gitlab-mr-commenter id=%q -->` (%q → JSON string).
+COMMENT_IDENTIFIER = "<!-- gitlab-mr-commenter id={} -->"
+
+
+def _marker(comment_id: str) -> str:
+    """Return the full hidden marker for *comment_id*.
+
+    Uses ``json.dumps`` to produce a double-quoted, escaped string — the same
+    output as Go's ``%q`` verb for plain ASCII identifiers.
+    """
+    return COMMENT_IDENTIFIER.format(json.dumps(comment_id))
+
+
+class MRCommenter:
+    """Post and idempotently update comments on a GitLab merge request.
+
+    Parameters
+    ----------
+    token:
+        GitLab personal / project / CI access token.  Falls back to the
+        ``GITLAB_MR_PLAN_TOKEN`` or ``GITLAB_TOKEN`` environment
+        variables.
+    api_url:
+        GitLab API v4 base URL (e.g. ``https://gitlab.com/api/v4``).  Falls
+        back to ``CI_API_V4_URL``.
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        api_url: Optional[str] = None,
+    ) -> None:
+        resolved_token = (
+            token
+            or os.environ.get("GITLAB_MR_PLAN_TOKEN")
+            or os.environ.get("GITLAB_TOKEN")
+        )
+        if not resolved_token:
+            raise ValueError(
+                "No GitLab token found. Pass token= or set "
+                "GITLAB_MR_PLAN_TOKEN / GITLAB_TOKEN."
+            )
+
+        resolved_url = api_url or os.environ.get("CI_API_V4_URL")
+        if not resolved_url:
+            raise ValueError(
+                "No GitLab API URL found. Pass api_url= or set CI_API_V4_URL."
+            )
+
+        self._gl = gitlab.Gitlab(resolved_url, private_token=resolved_token)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def post(
+        self,
+        content: str,
+        project_id: Optional[int] = None,
+        mr_iid: Optional[int] = None,
+        comment_id: str = "gitlab-mr-commenter",
+    ) -> None:
+        """Post or update a comment on a merge request.
+
+        If a note whose body contains the hidden marker for *comment_id*
+        already exists, it is updated in place.  Otherwise a new note is
+        created.
+
+        Parameters
+        ----------
+        content:
+            Markdown body of the comment (without the trailing marker — that
+            is appended automatically).
+        project_id:
+            Numeric GitLab project ID. Falls back to ``$CI_PROJECT_ID``.
+        mr_iid:
+            Merge request **internal** ID — the project-scoped number shown
+            in the URL. Falls back to ``$CI_MERGE_REQUEST_IID``.
+        comment_id:
+            Opaque string that uniquely names this comment slot. Two calls
+            with the same *comment_id* on the same MR update the same note.
+            Defaults to ``"gitlab-mr-commenter"``.
+        """
+        if project_id is None:
+            raw = os.environ.get("CI_PROJECT_ID", "")
+            if not raw:
+                raise ValueError(
+                    "project_id not provided and CI_PROJECT_ID is not set."
+                )
+            project_id = int(raw)
+
+        if mr_iid is None:
+            raw = os.environ.get("CI_MERGE_REQUEST_IID", "")
+            if not raw:
+                raise ValueError(
+                    "mr_iid not provided and CI_MERGE_REQUEST_IID is not set."
+                )
+            mr_iid = int(raw)
+
+        marker = _marker(comment_id)
+        body = f"{content}\n\n{marker}"
+
+        project = self._gl.projects.get(project_id)
+        mr = project.mergerequests.get(mr_iid)
+
+        # Walk all pages lazily; stop as soon as we find a matching note.
+        for note in mr.notes.list(as_list=False):
+            if marker in note.body:
+                note.body = body
+                note.save()
+                return
+
+        # No existing comment — create one.
+        mr.notes.create({"body": body})
+
+
+def post_comment(
+    content: str,
+    project_id: Optional[int] = None,
+    mr_iid: Optional[int] = None,
+    comment_id: str = "gitlab-mr-commenter",
+    *,
+    token: Optional[str] = None,
+    api_url: Optional[str] = None,
+) -> None:
+    """Convenience wrapper around :class:`MRCommenter`.
+
+    All parameters mirror :meth:`MRCommenter.post`; *token* and *api_url*
+    fall back to the same environment variables as the constructor.
+    """
+    MRCommenter(token=token, api_url=api_url).post(
+        content, project_id, mr_iid, comment_id
+    )

gitlab_mr_commenter-2.0.1/gitlab_mr_commenter/__main__.py

@@ -0,0 +1,115 @@
+"""CLI entry point for gitlab-mr-commenter.
+
+Usage
+-----
+Minimal — all values from CI environment variables::
+
+    echo "## Plan" | gitlab-mr-commenter
+
+With an explicit comment slot name::
+
+    echo "## Plan" | gitlab-mr-commenter plan-production
+
+Fully explicit::
+
+    echo "## Plan" | gitlab-mr-commenter \\
+        --project-id 123 \\
+        --mr-iid 45 \\
+        --token "$GITLAB_TOKEN" \\
+        --api-url "https://gitlab.com/api/v4" \\
+        plan-production
+
+Also callable as a module::
+
+    echo "## Plan" | python -m gitlab_mr_commenter
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import MRCommenter
+
+
+DEFAULT_COMMENT_ID = "gitlab-mr-commenter"
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="gitlab-mr-commenter",
+        description=(
+            "Post or update a GitLab MR comment identified by COMMENT_ID. "
+            "Content is read from stdin. Re-running with the same COMMENT_ID "
+            "updates the existing comment in place."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "environment variables (used when flags are omitted):\n"
+            "  CI_PROJECT_ID              GitLab project ID\n"
+            "  CI_MERGE_REQUEST_IID       MR internal ID\n"
+            "  CI_API_V4_URL              GitLab API base URL\n"
+            "  GITLAB_MR_PLAN_TOKEN  API token (preferred)\n"
+            "  GITLAB_TOKEN          API token (deprecated fallback)\n"
+        ),
+    )
+
+    parser.add_argument(
+        "comment_id",
+        metavar="COMMENT_ID",
+        nargs="?",
+        default=DEFAULT_COMMENT_ID,
+        help=(
+            f"Unique name for this comment slot (default: '{DEFAULT_COMMENT_ID}'). "
+            "A second run with the same value updates the existing comment."
+        ),
+    )
+    parser.add_argument(
+        "--project-id",
+        type=int,
+        default=None,
+        metavar="ID",
+        help="GitLab project ID. Defaults to $CI_PROJECT_ID.",
+    )
+    parser.add_argument(
+        "--mr-iid",
+        type=int,
+        default=None,
+        metavar="IID",
+        help="Merge request internal ID. Defaults to $CI_MERGE_REQUEST_IID.",
+    )
+    parser.add_argument(
+        "--token",
+        default=None,
+        metavar="TOKEN",
+        help=(
+            "GitLab API token. Defaults to $GITLAB_MR_PLAN_TOKEN " "or $GITLAB_TOKEN."
+        ),
+    )
+    parser.add_argument(
+        "--api-url",
+        default=None,
+        metavar="URL",
+        help="GitLab API base URL. Defaults to $CI_API_V4_URL.",
+    )
+
+    args = parser.parse_args(argv)
+
+    content = sys.stdin.read()
+    if not content.strip():
+        parser.error("stdin is empty — nothing to post.")
+
+    try:
+        MRCommenter(token=args.token, api_url=args.api_url).post(
+            content=content,
+            project_id=args.project_id,
+            mr_iid=args.mr_iid,
+            comment_id=args.comment_id,
+        )
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

gitlab_mr_commenter-2.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitlab-mr-commenter"
+version = "2.0.1"
+description = "Post and idempotently update comments on GitLab merge requests"
+requires-python = ">=3.9"
+dependencies = [
+    "python-gitlab>=8.0",
+]
+authors = [
+    {name = "Gian Klug", email = "gk@gk.wtf"}
+]
+
+[project.scripts]
+gitlab-mr-commenter = "gitlab_mr_commenter.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["gitlab_mr_commenter"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+changelog_file = "CHANGELOG.md"
+build_command = "uv build"
+tag_format = "v{version}"
+
+[tool.semantic_release.commit_parser_options]
+# Conventional commits: feat → minor, fix/perf → patch, BREAKING CHANGE → major
+allowed_tags = ["feat", "fix", "perf", "refactor", "docs", "chore", "ci"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]