close-gitlab-mr

name	close-gitlab-mr
description	Merge and close GitLab merge requests with glab after provider-specific pipeline gating, draft readiness, merge, and local cleanup.

Close GitLab MR

Contract

Prereqs:

• Run inside the target GitLab-backed git repo.
• git, glab, and python3 available on PATH, and glab auth status succeeds for the target host.
• Working tree clean (git status --porcelain=v1 is empty).

Inputs:

• kind=feature|bug|config|deploy|docs|chore.
• MR IID/branch, or current-branch MR when --mr is omitted.
• Optional user-requested pre-close specialist review through code-review-specialists.
• Optional pipeline controls: --poll-seconds <n>, --max-wait-seconds <n>, --skip-pipeline, and --allow-no-pipeline.
• Optional merge controls: --remove-source-branch, --squash, and --sha <commit>.
• Optional local cleanup controls: --keep-local-branch and --no-cleanup.

Outputs:

• MR pipeline verified as passing, or explicitly accepted as missing with --allow-no-pipeline.
• User-requested pre-close specialist review completed before merge, when requested, with no concrete findings waiting on user decision.
• Draft MRs marked ready with glab mr update <mr> --ready --yes before merge.
• MR merged with glab mr merge.
• Remote source branch removed only when --remove-source-branch is supplied.
• Local checkout switched back to target branch and updated; local source branch deleted unless --keep-local-branch or --no-cleanup is supplied.

Exit codes:

• 0: success
• 1: workflow blocked/failure (dirty tree, missing pipeline without explicit allow, failed pipeline, non-open MR, merge failure, command failure)
• 2: usage error
• 124: pipeline wait timeout

Failure modes:

• Pipeline is missing and --allow-no-pipeline was not supplied.
• Pipeline is failing, canceled, skipped, blocked, manual/action-required, still pending, or unknown.
• User-requested pre-close specialist review reports concrete findings that need user decision before merge.
• MR is draft and automatic glab mr update --ready fails.
• MR is not open, not mergeable, or glab/git permissions are insufficient.

Scripts (only entrypoints)

• $AGENT_HOME/skills/workflows/mr/gitlab/close-gitlab-mr/scripts/close-gitlab-mr.sh

Optional User-Requested Review

• This gate is optional. Run it only when the user explicitly asks for review, specialist review, or review before close.
• End-to-end deliver-gitlab-mr runs the mandatory shared delivery specialist review gate before invoking this close workflow. Keep this direct close gate optional so existing MR close/cleanup requests do not become implicit review orchestration.
• Run it before invoking close-gitlab-mr.sh for final merge and cleanup; the close helper has no review flag.
• Resolve the MR IID and target branch with glab mr view, then use the MR target branch as the code-review-specialists diff base.
• Keep code-review-specialists read-only: do not post MR comments, fix code, mark the MR ready, merge, or clean up from that workflow.
• Honor the code-review-specialists scope and skip rules unless the user forced a specialist or all specialists.
• If the specialist report contains concrete findings, stop before merge and report them for user decision. If there are no concrete findings, or the user explicitly accepts them, continue the normal close workflow.

Shared delivery gate reference: skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md

Workflow

1. Resolve MR metadata

   • Resolve MR URL, target branch, source branch, state, and draft state through glab mr view.

2. Run optional user-requested review

   • If the user requested pre-close review, complete the optional review gate before invoking the close helper.

3. Gate on GitLab pipeline

   • Default behavior blocks missing pipelines:
     • close-gitlab-mr.sh --kind <kind> --mr <iid>
   • Repositories without CI require explicit acknowledgement:
     • close-gitlab-mr.sh --kind <kind> --mr <iid> --allow-no-pipeline
   • --allow-no-pipeline only accepts a missing pipeline. It must not bypass failed, skipped, blocked, manual, pending, or unknown pipeline states.
   • --skip-pipeline is reserved for explicit user-confirmed cases where the pipeline gate should not run at all.
   • For repos whose source-branch pipeline is intentionally skipped and whose real build/deploy gate is target-branch CI, verify MR mergeability and the target-branch validation model before using explicit --skip-pipeline.

4. Mark ready and merge

   • If draft, run glab mr update <mr> --ready --yes automatically.
   • Merge with glab mr merge <mr> --yes.
   • Pass --remove-source-branch, --squash, and --sha <commit> only when explicitly supplied.

5. Cleanup

   • Switch to the target branch, fetch origin/<target>, fast-forward the local target branch, and delete the local source branch unless cleanup is disabled.
   • If the target branch is locked by another worktree, fall back to detached origin/<target> for local branch deletion.

Kind Policy

• kind=feature: use for feature MRs originally created by create-gitlab-mr.
• kind=bug: use for bugfix MRs originally created by create-gitlab-mr.
• kind=docs: use for documentation-only MRs originally created by create-gitlab-mr.
• kind=config|deploy|chore: use for operational/configuration MRs originally created by create-gitlab-mr.
• The close mechanics are provider-specific and shared across kinds; kind is retained for auditability and composition by deliver-gitlab-mr.