Merge pull request #862 from ALERTua/feat/rebase-head-changed

feat: report whether rebase_merge_request moved the head

Author: zereight

.well-known/mcp/server-card.json

@@ -10829,7 +10829,7 @@
     },
     {
       "name": "rebase_merge_request",
-      "description": "Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
+      "description": "Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request plus `previous_sha` (its `sha` before the rebase) and `head_changed`. `head_changed: false` means that the head did not move; `merge_error` gives the reason when GitLab sends one. `merge_error` can keep a message from an earlier attempt, so it alone does not prove that this attempt failed. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
       "inputSchema": {
         "type": "object",
         "properties": {

CHANGELOG.md

@@ -8,6 +8,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
 ##### Changed
 
+- `rebase_merge_request` with `wait` true (default) now also returns `previous_sha` (the head `sha` before the rebase) and `head_changed`, so a caller sees at once whether the rebase moved the head ([#862](https://github.com/zereight/gitlab-mcp/pull/862)).
 - Boolean tool arguments now parse the string `"false"` as `false` ([#848](https://github.com/zereight/gitlab-mcp/pull/848)). Other non-boolean strings such as `""` or `"yes"`, previously coerced to `true`, are now rejected with a validation error.
 - Tool argument validation failures are now returned as tool results with `isError: true` instead of JSON-RPC errors, so the model sees which arguments to fix and can retry. The message names the tool and each invalid field, for example `Invalid arguments for verify_namespace: path: Invalid input: expected string, received undefined`. Clients that caught these as protocol errors (`MCP error -32603`) must now check `isError` on the result. GitLab responses that fail schema parsing are still JSON-RPC errors, now reported as `Unexpected GitLab response for <tool>: ...` instead of `Invalid arguments: ...`.
 

docs/tools/index.md

@@ -180,7 +180,7 @@ MR lifecycle — create, update, merge, approve, plus diff/conflict inspection a
 | Tool | What it does | R/W |
 |---|---|:-:|
 | [`merge_merge_request`](merge-requests.md#merge_merge_request) | Merge a merge request. Use this only after checking the merge request approval, conflict, and pipeline state; use `approve_merge_request` to approve rather than merge. The operation changes repository state and may squash commits, schedule auto-merge, or delete the source branch, so it requires merge permission and returns GitLab's merge result or a mergeability error. Pass `sha` from `get_merge_request` (`sha` or `diff_refs.head_sha`); GitLab 19.2+ groups may reject merges without it. | ✏️ |
-| [`rebase_merge_request`](merge-requests.md#rebase_merge_request) | Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch. | ✏️ |
+| [`rebase_merge_request`](merge-requests.md#rebase_merge_request) | Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request plus `previous_sha` (its `sha` before the rebase) and `head_changed`. `head_changed: false` means that the head did not move; `merge_error` gives the reason when GitLab sends one. `merge_error` can keep a message from an earlier attempt, so it alone does not prove that this attempt failed. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch. | ✏️ |
 | [`approve_merge_request`](merge-requests.md#approve_merge_request) | Approve a merge request. Use this to record an approval on an existing merge request; it does not merge the request or change its source branch. The operation changes review state, may require re-authentication or approval permission, and returns the updated approval result or a permission/state error. | ✏️ |
 | [`unapprove_merge_request`](merge-requests.md#unapprove_merge_request) | Unapprove a merge request. Use this to remove the current user's approval from an existing merge request; use `merge_merge_request` only when you intend to merge. The operation changes review state and requires approval permission, and GitLab returns the updated result or an error when the request or approval is unavailable. | ✏️ |
 | [`get_merge_request_approval_state`](merge-requests.md#get_merge_request_approval_state) | Get merge request approval details including approvers. Use this to inspect approval rules and approvers before deciding whether a merge request can be merged; use `approve_merge_request` to change approval state. It is read-only and returns the approval-state response, while missing requests, unsupported GitLab versions, and permission failures are reported as errors. | 📖 |

docs/tools/merge-requests.md

@@ -80,7 +80,7 @@ Merge a merge request. Use this only after checking the merge request approval,
 
 *✏️ Writes*
 
-Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.
+Rebase the source branch of a merge request onto its target branch. Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request plus `previous_sha` (its `sha` before the rebase) and `head_changed`. `head_changed: false` means that the head did not move; `merge_error` gives the reason when GitLab sends one. `merge_error` can keep a message from an earlier attempt, so it alone does not prove that this attempt failed. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.
 
 **Parameters**
 

index.ts

@@ -12521,17 +12521,27 @@ async function handleToolCall(params: any) {
           timeout_seconds,
           poll_interval_seconds,
         } = RebaseMergeRequestSchema.parse(params.arguments);
-        const enqueued = await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
         if (!wait) {
+          const enqueued = await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
           return { content: [{ type: "text", text: JSON.stringify(enqueued) }] };
         }
+        const { mergeRequest: previous } = await getMergeRequestRebaseStatus(
+          project_id,
+          merge_request_iid
+        );
+        await rebaseMergeRequest(project_id, merge_request_iid, skip_ci);
         const { mergeRequest } = await waitForStatus(
           signal => getMergeRequestRebaseStatus(project_id, merge_request_iid, signal),
           TERMINAL_REBASE_STATUSES,
           timeout_seconds,
           poll_interval_seconds
         );
-        return { content: [{ type: "text", text: JSON.stringify(mergeRequest) }] };
+        const rebaseResult = {
+          ...mergeRequest,
+          previous_sha: previous.sha,
+          head_changed: mergeRequest.sha !== previous.sha,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(rebaseResult) }] };
       }
 
       case "get_merge_request_approval_state": {

skills/gitlab-mcp/SKILL.md

@@ -125,6 +125,7 @@ Enable with `GITLAB_TOOLSETS=vulnerabilities` (requires GitLab Ultimate).
 - **MR lookup**: provide `merge_request_iid` or `source_branch`
 - **list_issues**: default scope = created by current user. Use `scope: "all"` for all issues
 - **list_merge_requests**: without project_id returns user's MRs across all projects
+- **rebase_merge_request**: with `wait` true (default) returns the merge request plus `previous_sha` and `head_changed`
 - **CI catalog resource lookup**: provide exactly one of `id` or `full_path`
 - **emoji reactions**: merge request, issue, and work item reaction tools use GitLab emoji names like `thumbsup`, `rocket`, or `eyes`
 - **work items**: status and custom fields require GitLab Premium/Ultimate features

skills/gitlab-mcp/reference/merge-requests.md

@@ -69,7 +69,7 @@ rebase_merge_request
   project_id: "my-group/my-project"
   merge_request_iid: 42
   skip_ci: true          # optional, no pipeline for the rebased branch
-  wait: true             # default; polls until the rebase ends
+  wait: true             # default; polls until the rebase ends and returns previous_sha and head_changed
 ```
 
 **Warning**: `rebase_merge_request` is destructive - it force-pushes the rebased source branch.

test/test-rebase-merge-request.ts

@@ -175,13 +175,15 @@ describe("rebase_merge_request tool", () => {
   let mockGitLabUrl: string;
   const rebaseBodies = new Map<string, Record<string, unknown>>();
   const statusQueries = new Map<string, Array<Record<string, unknown>>>();
+  const statusQueriesBeforeRebase = new Map<string, number>();
 
   function addRebaseHandler(iid: string) {
     mockGitLab.addMockHandler(
       "put",
       `/projects/${TEST_PROJECT_ID}/merge_requests/${iid}/rebase`,
       (req, res) => {
         rebaseBodies.set(iid, req.body);
+        statusQueriesBeforeRebase.set(iid, statusQueries.get(iid)?.length ?? 0);
         res.status(202).json({ rebase_in_progress: true });
       }
     );
@@ -212,12 +214,18 @@ describe("rebase_merge_request tool", () => {
       addRebaseHandler(iid);
     }
     addStatusHandler(MR_ENQUEUE_ONLY, [{ rebase_in_progress: true }]);
+    // The first GET of a waiting call reads the head before the rebase.
     addStatusHandler(MR_SUCCESS, [
+      { rebase_in_progress: false },
       { rebase_in_progress: true },
       { rebase_in_progress: false, sha: NEW_SHA },
     ]);
-    addStatusHandler(MR_FAILED, [{ rebase_in_progress: false, merge_error: REBASE_FAILED }]);
+    addStatusHandler(MR_FAILED, [
+      { rebase_in_progress: false },
+      { rebase_in_progress: false, merge_error: REBASE_FAILED },
+    ]);
     addStatusHandler(MR_TIMEOUT, [{ rebase_in_progress: true }]);
+    addStatusHandler(MR_FORBIDDEN, [{ rebase_in_progress: false }]);
 
     mockGitLab.addMockHandler(
       "put",
@@ -263,7 +271,7 @@ describe("rebase_merge_request tool", () => {
     assert.deepStrictEqual(rebaseBodies.get(MR_SKIP_CI), { skip_ci: true });
   });
 
-  test("rebase_merge_request polls until the rebase ends and returns the merge request", async () => {
+  test("rebase_merge_request polls until the rebase ends and reports that the head moved", async () => {
     const result = await callTool(
       "rebase_merge_request",
       { project_id: TEST_PROJECT_ID, merge_request_iid: MR_SUCCESS, poll_interval_seconds: 1 },
@@ -273,12 +281,15 @@ describe("rebase_merge_request tool", () => {
     assert.strictEqual(result.rebase_in_progress, false);
     assert.strictEqual(result.merge_error, null);
     assert.strictEqual(result.sha, NEW_SHA);
+    assert.strictEqual(result.previous_sha, OLD_SHA);
+    assert.strictEqual(result.head_changed, true);
     const queries = statusQueries.get(MR_SUCCESS) ?? [];
-    assert.strictEqual(queries.length, 2);
+    assert.strictEqual(queries.length, 3);
+    assert.strictEqual(statusQueriesBeforeRebase.get(MR_SUCCESS), 1);
     assert.ok(queries.every(query => query.include_rebase_in_progress === "true"));
   });
 
-  test("rebase_merge_request returns merge_error when the rebase fails", async () => {
+  test("rebase_merge_request returns merge_error and an unmoved head when the rebase fails", async () => {
     const result = await callTool(
       "rebase_merge_request",
       { project_id: TEST_PROJECT_ID, merge_request_iid: MR_FAILED },
@@ -287,6 +298,9 @@ describe("rebase_merge_request tool", () => {
 
     assert.strictEqual(result.rebase_in_progress, false);
     assert.strictEqual(result.merge_error, REBASE_FAILED);
+    assert.strictEqual(result.previous_sha, OLD_SHA);
+    assert.strictEqual(result.head_changed, false);
+    assert.strictEqual(statusQueries.get(MR_FAILED)?.length, 2);
   });
 
   test("rebase_merge_request reports a timeout while the rebase still runs", async () => {

tools/tool-descriptions.ts

@@ -6,7 +6,7 @@ const TOOL_GUIDANCE: Readonly<Record<string, string>> = {
   unapprove_merge_request:
     "Use this to remove the current user's approval from an existing merge request; use `merge_merge_request` only when you intend to merge. The operation changes review state and requires approval permission, and GitLab returns the updated result or an error when the request or approval is unavailable.",
   rebase_merge_request:
-    "Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request: GitLab reports a failed rebase in `merge_error`, but that field can also keep a message from an earlier attempt, so compare `sha` with its value before the rebase. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
+    "Use this when the source branch is behind its target branch; use `get_merge_request_conflicts` to inspect conflicts and `merge_merge_request` to merge. The operation rewrites the source branch history with a force push and requires permission to push to that branch. With `wait` true (default), it polls until the rebase ends and returns the merge request plus `previous_sha` (its `sha` before the rebase) and `head_changed`. `head_changed: false` means that the head did not move; `merge_error` gives the reason when GitLab sends one. `merge_error` can keep a message from an earlier attempt, so it alone does not prove that this attempt failed. If the rebase still runs after `timeout_seconds`, it returns a timeout error while GitLab continues the rebase. With `wait` false, it returns GitLab's enqueue response (`rebase_in_progress` true) at once. Set `skip_ci` to skip the CI pipeline for the rebased branch.",
   get_merge_request_approval_state:
     "Use this to inspect approval rules and approvers before deciding whether a merge request can be merged; use `approve_merge_request` to change approval state. It is read-only and returns the approval-state response, while missing requests, unsupported GitLab versions, and permission failures are reported as errors.",
   get_merge_request_conflicts: