gitlab-merge-request

# Merge Requests Working with GitLab merge requests via `glab mr`. Scripts directory (absolute, for invocations from other skills where `${CLAUDE_SKILL_DIR}` points elsewhere): !`mkdir -p /tmp/claude/gitlab-skill 2>/dev/null; touch "/tmp/claude/gitlab-skill/${CLAUDE_SESSION_ID}" 2>/dev/null; echo "${CLAUDE_SKILL_DIR}/scripts"` ## Arguments `$0` (optional verb) routes to a section below. With no verb, infer the operation from the request. - `create`: open an MR. See [Patterns](#patterns). `--draft` opens it as a draft (`glab mr create --draft`). - `merge`: merge the MR. See [Merging](#merging). `--auto` enables auto-merge (`merge.ts --auto-merge`). - `review`: review MRs. See [Reviews](#reviews). `--role reviewer` (default) fetches MRs awaiting your review; `--role author` triages threads on MRs you authored. - `discussions`: work MR discussion threads. See [Discussions](#discussions). - `block`: block an MR until another merges. See [Blocking](#blocking). Flag defaults: `--draft` off, `--auto` off, `--role reviewer`. ## Merging Always use `merge.ts` to merge. It handles merge trains, auto-merge, and squash, falling back to `glab mr merge` internally when appropriate. ```bash bun ${CLAUDE_PLUGIN_ROOT}/scripts/merge.ts bun ${CLAUDE_PLUGIN_ROOT}/scripts/merge.ts --auto-merge bun ${CLAUDE_PLUGIN_ROOT}/scripts/merge.ts feature-branch --auto-merge --squash ``` Never call `glab mr merge` directly. It turns auto-merge on by default whenever a pipeline is running. A bare invocation then queues the MR to merge itself later instead of merging it now, silently breaking a deliberate merge order. `merge.ts` always sends `--auto-merge=<choice>` so the default cannot apply. ### Inspect Before Merging `--status` prints the MR's merge readiness as JSON and exits without touching it: target branch, draft state, `detailed_merge_status`, head pipeline, and a `rebased_on_target` ancestry check computed from git rather than the API's stale conflict fields. ```bash bun ${CLAUDE_PLUGIN_ROOT}/scripts/merge.ts --status bun ${CLAUDE_PLUGIN_ROOT}/scripts/merge.ts feature-branch --status ``` ### Re-Arm Auto-Merge After a Push Pushing new commits cancels queued auto-merge and drops the MR from the merge train. GitLab does this deliberately so the new commits get a fresh pipeline and review. To keep auto-merge, re-run `merge.ts --auto-merge` after every push that intends to stay armed. The script is idempotent: it treats an already-armed MR as success and retries through the brief `approvals_syncing` window that follows a push, so re-running it is always safe. A push also resets approvals when `reset_approvals_on_push` is on. Re-trigger review in the same pass, see [Re-request reviewers](#re-request-reviewers). ### Inspect or Recover a Train To inspect the active train or clear a stuck entry via the API (`glab` has no merge-train command), see [merge-trains.md](merge-trains.md). ## Stacked MRs Merging one layer of a stack leaves the layer above it targeting a branch that already merged. GitLab does not retarget it. Retarget, rebase, and verify after every layer, see [stacked-mrs.md](stacked-mrs.md). ## Patterns **Always push before creating:** ```bash git push -u origin feature-branch && glab mr create --fill ``` **Draft MRs:** Use `--draft` to prevent accidental merges. **Auto-fill vs custom:** `--fill` auto-populates from commits but cannot combine with `--title`/`--description`. Choose one approach. **Body from file:** The flag is `--description-file file.md`, not gh's `--body-file`. Prefer it over `--description "$(cat file.md)"`, which passes the body through the shell and keeps it out of some hooks. **Screenshots:** `glab mr` has no attach flag. Upload each file through project uploads per `gitlab:api` and paste the returned markdown into the description before creating. **Username resolution:** Flags like `--reviewer` and `--assignee` require exact usernames; invalid names are silently ignored. Look up users first: ```bash glab api projects/:id/members/all --paginate | jq '.[] | select(.name | test("<name>"; "i")) | {name, username}' ``` ## Blocking Block an MR from merging until another MR merges first (`block` verb). See [blocking.md](blocking.md) for the REST API commands. ## Reviews Submit review feedback as draft notes that accumulate before publishing. See [review.md](review.md) for the draft notes workflow, code suggestions, and approvals. Fetch MRs awaiting your first review across all projects (the `UNREVIEWED` bucket; REST's `scope=reviews_for_me` cannot filter by review state). Emits `[{ url, reference, title }]` as JSON: ```bash bun ${CLAUDE_SKILL_DIR}/scripts/review-queue.ts ``` See [review-state.md](review-state.md) for the underlying GraphQL query and filter. To group all your review-requested MRs by next actor (not just the `UNREVIEWED` slice), see [Review Inbox (Next-Actor Triage)](review-state.md#review-inbox-next-actor-triage) in review-state.md. ## Re-request reviewers Re-trigger a review after a push reset approvals. The `mergeRequestReviewerRereview` mutation flips the target's `reviewState` back to `UNREVIEWED` and re-surfaces the MR. The reviewer must already be assigned. See [Re-Request Review](review-state.md#re-request-review) for the user-ID lookup and exact mutation. ## Discussions Fetch, filter, resolve, and summarize MR discussion threads. ```bash # Open threads, one line each bun ${CLAUDE_SKILL_DIR}/scripts/discussions.ts list <iid> --resolvable --unresolved --format digest # Only review-bot threads bun ${CLAUDE_SKILL_DIR}/scripts/discussions.ts list <iid> --bots --reviewers=${user_config.reviewers} bun ${CLAUDE_SKILL_DIR}/scripts/discussions.ts resolve <iid> <discussion-id>... ``` See [discussions.md](discussions.md) for the other commands, output formats, and pagination pitfalls.