gitlab-mr-inline-comment

name	gitlab-mr-inline-comment
description	Publish a single inline comment on a GitLab merge request by anchoring it to a valid diff line with `glab api`. Use when Codex needs to place one review comment on a specific MR file and line, while reusing the user's existing `glab` authentication and stopping on invalid anchors instead of falling back to a general comment.
metadata	{"name":"GitLab MR Inline Comment","description":"Post a single anchored GitLab MR inline comment with host-aware `glab` usage.","author":"Flc","created":"2026-03-30T02:46:31.000Z"}

GitLab MR Inline Comment

Publish one anchored inline comment on a GitLab merge request.

Operating Mode

Act as a narrow GitLab review helper.

Prioritize:

• correct GitLab host and repository context before any write
• valid MR diff SHAs before payload assembly
• valid file path and line anchors before posting
• explicit failure over silent downgrade to a general comment
• reuse of the user's existing glab authentication and repository context

Assume glab is installed unless local evidence shows otherwise.

Do not require extra tokens, .env files, or custom auth setup when the user's existing glab session already has access.

Read these references only when needed:

• exact command patterns: references/verified-commands.md
• payload shape and field semantics: references/api-shape.md
• current MR version and anchor resolution: references/current-diff-resolution.md
• common failure cases and stop conditions: references/failure-modes.md

Required Inputs

Collect or derive these values before posting:

• mr_iid
• body
• old_path
• new_path
• one valid line anchor shape:
  • added line: new_line
  • removed line: old_line
  • unchanged line: both old_line and new_line

Resolve one repository context:

• current repository glab context, or
• explicit GitLab project path such as group/subgroup/repo, or
• a GitLab merge request URL that can be parsed into host, project, and MR IID

Resolve these MR diff fields from the current merge request version:

• base_sha
• start_sha
• head_sha

Workflow

Follow this sequence unless the user asks for one narrower part.

1. Confirm GitLab context with the lightest viable command

Prefer the user's current repository context first.

Use bare glab commands when the current directory is already the target GitLab repository.

Only inspect git remote -v, add GITLAB_HOST, or use explicit repository arguments when:

• glab resolves to the wrong host
• the task targets another repository
• authentication fails against an unexpected instance
• the user provides a merge request URL on another GitLab host

Do not introduce extra authentication if glab auth status already shows valid access for the target host.

2. Identify the target merge request

Normalize the task to one merge request.

If the user gives a merge request URL, parse it into:

• host
• project path
• MR IID

If the user gives a project path and MR IID, use them directly.

If the current repository is already the target project, prefer repository-context commands over manual URL construction.

3. Read the current MR version SHAs

Before building the discussion payload, fetch the merge request state needed for inline anchors.

Use references/current-diff-resolution.md when exact field names or version-selection rules matter.

Resolve:

• base_sha
• start_sha
• head_sha

Do not guess or reuse stale SHAs from old output.

If the current MR version cannot be read reliably, stop and report that inline comment posting is blocked by missing diff context.

4. Validate the anchor

Confirm that:

• old_path and new_path match the current MR diff position
• the line anchor matches one valid text diff case:
  • added line: new_line only
  • removed line: old_line only
  • unchanged line: both old_line and new_line

Use references/current-diff-resolution.md when deciding whether the target line is safely anchorable.

Do not guess the path or line.

Do not silently switch to a general merge request comment when the anchor is invalid.

5. Build the payload and post the discussion

Use the minimal payload shape from references/api-shape.md.

Post to the merge request discussions endpoint with glab api.

Use the user's existing glab authentication and host context whenever possible.

6. Return a concise result

On success, report:

• target project and MR IID
• anchored paths and line position
• short confirmation that the inline comment was posted

On failure, report the concrete blocking reason, such as:

• host or auth mismatch
• missing MR version SHAs
• path not in diff
• line not commentable
• GitLab API validation error

Output Structure

When the task is to post the comment directly, summarize the execution result like this:

# Inline Comment Result

## Target
- project: <group/subgroup/repo>
- mr: !<iid>
- old_path: <old_path>
- new_path: <new_path>
- old_line: <old_line or omitted>
- new_line: <new_line or omitted>

## Result
- status: <posted | failed>
- detail: <short reason or confirmation>

Decision Rules

• Prefer repository-context glab commands over manual encoded project IDs when the current directory already matches the target project.
• Use explicit GITLAB_HOST only when the target host differs from the current repository context or glab resolves incorrectly.
• Treat inline comment posting as blocked when the current MR diff SHAs are unavailable or ambiguous.
• Treat invalid anchors as hard failures.
• Keep v1 limited to one text diff inline comment with one valid position shape.

Red Flags

Stop and reassess if:

• multiple GitLab hosts are present and the write target is unclear
• the authenticated host and intended host disagree
• the merge request URL, project, or IID do not resolve to one clear target
• base_sha, start_sha, and head_sha cannot be read from the current MR state
• old_path or new_path cannot be reconciled with the current diff position
• the provided old_line / new_line combination does not form a valid text diff anchor
• the only fallback would be posting a non-inline general comment

Out Of Scope For V1

Do not add these behaviors in v1:

• multi-line or range comments
• batch comment publishing
• draft review or pending review workflows
• automatic comment placement based on code analysis
• automatic downgrade to a general merge request note