deliver-gitlab-mr

name	deliver-gitlab-mr
description	Deliver GitLab merge requests end to end with one workflow: preflight, create via create-gitlab-mr, wait/fix pipeline until green, then close via close-gitlab-mr.

Deliver 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 may be dirty before preflight; preflight must run scope triage first.
• Working tree must be clean before merge.
• Companion skills available: create-gitlab-mr, close-gitlab-mr, and code-review-specialists.

Inputs:

• kind=feature|bug|config|deploy|docs|chore.
• MR outcome summary plus target branch, source branch, testing notes, and related deployment/config evidence when applicable.
• Optional MR IID or current-branch MR resolution.
• Optional base branch for preflight (default: main).
• Mandatory pre-close specialist review using the shared delivery specialist review gate; this is an orchestration gate, not a script flag.
• Optional user authorization to fix concrete pre-close review findings before close.
• Optional merge controls: --remove-source-branch, --squash, --sha <commit>, --skip-pipeline, --allow-no-pipeline, --keep-local-branch, and --no-cleanup.
• Optional ambiguity bypass flag for preflight: --bypass-ambiguity (alias: --proceed-all). Use only after explicit user confirmation that suspicious files are in scope.

Outputs:

• Branch created from the confirmed base branch when new work is needed:
  • kind=feature -> feat/<slug>
  • kind=bug -> fix/<slug>
  • kind=docs -> docs/<slug>
  • kind=config|deploy|chore -> chore/<slug>
• A GitLab MR created through create-gitlab-mr.
• Pipeline status fully green; failed or blocked pipelines are fixed before merge.
• A code-review-specialists review pass completed before merge with at least testing and maintainability forced, even for small diffs.
• A delivery review outcome comment posted to the MR before merge, using agent-kit:delivery-review-outcome:v1, listing review lenses, validation, pipeline status, concrete finding dispositions, and the merge/block decision.
• MR marked ready when it is draft, merged, and cleaned up through close-gitlab-mr.
• deliver-gitlab-mr is successful only after close/merge is complete; create-only is not a successful delivery outcome.

Exit codes:

• 0: success
• 1: workflow blocked/failure (branch mismatch, pipeline failure, auth issues, command failure)
• 2: usage error
• 124: pipeline wait timeout

Failure modes:

• Initial branch is not the expected base branch (main by default):
  • Stop immediately and ask the user to confirm source branch and target branch.
• glab auth status fails or exceeds AGENT_KIT_GLAB_AUTH_TIMEOUT_SEC (default: 30):
  • Stop and report GitLab auth/network status before attempting MR creation or merge.
• Pipeline fails, is canceled, is skipped, is blocked, or requires a manual action:
  • Do not merge; fix issues on the delivery branch, push, and re-run pipeline wait.
• No pipeline exists for the source branch:
  • Stop by default; continue only when the user explicitly supplied --allow-no-pipeline.
• Mandatory pre-close specialist review reports concrete findings:
  • If the user did not explicitly authorize fixing review findings before close, stop before close and ask whether to fix, accept, or abort.
  • If the user explicitly authorized fixes, repair the findings on the delivery branch, rerun validation and pipeline gates, rerun the affected specialist review when useful, then re-enter close.
• Delivery review outcome comment cannot be posted:
  • Do not merge.
  • Report the failed glab mr note create command, exit status, and retry action.
• Skill conflict or ambiguity (branch target, merge strategy, source branch deletion, or "skip pipeline"):
  • Stop and ask the user to confirm the canonical workflow before continuing.
• MR remains draft and automatic glab mr update --ready fails during merge.
• Missing glab auth/permissions, wrong GitLab project, or non-mergeable MR.

Scripts (only entrypoints)

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

Workflow

1. Choose kind

   • Use kind=feature for feature delivery. Branch prefix is feat/.
   • Use kind=bug for bugfix delivery. Branch prefix is fix/.
   • Use kind=docs for documentation-only delivery. Branch prefix is docs/.
   • Use kind=config, kind=deploy, or kind=chore for operational/configuration delivery. Branch prefix is chore/.

2. Branch-intent preflight (mandatory)

   • Run:
     • deliver-gitlab-mr.sh --kind <kind> preflight --base main
   • Optional explicit bypass run (non-blocking mode):
     • deliver-gitlab-mr.sh --kind <kind> preflight --base main --bypass-ambiguity
   • Contract:
     • This delivery method starts from the confirmed base branch, creates or reuses a source branch, and targets the confirmed target branch.
     • Preflight must classify staged/unstaged/untracked changes and apply the suspicious-signal matrix.
     • Preflight must bound glab auth status with AGENT_KIT_GLAB_AUTH_TIMEOUT_SEC so GitLab network/auth failures do not hang delivery.
     • If current branch is not main (or not the user-confirmed base), stop and ask the user.
     • --bypass-ambiguity only bypasses ambiguity block payloads after explicit user approval. It does not bypass branch guard, auth checks, or later pipeline gates.

3. Create MR

   • Use create-gitlab-mr to:
     • create or reuse the source branch
     • implement + test
     • commit + push
     • open a draft MR by default
   • MR creation must keep the audited marker required by create-gitlab-mr: AGENT_KIT_PR_SKILL=create-gitlab-mr.

4. Wait for pipeline and repair until green

   • Run:
     • deliver-gitlab-mr.sh --kind <kind> wait-pipeline --mr <iid>
   • For repositories without CI, use explicit no-pipeline acknowledgement:
     • deliver-gitlab-mr.sh --kind <kind> wait-pipeline --mr <iid> --allow-no-pipeline
   • If any pipeline fails or blocks:
     • fix on the same delivery branch
     • push updates
     • re-run wait-pipeline
   • Do not proceed to merge until the pipeline is green, unless the user explicitly confirms --allow-no-pipeline or --skip-pipeline.
   • 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.

5. Run mandatory specialist review

   • Follow the shared delivery specialist review gate: skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md.
   • Resolve the MR IID and target branch with glab mr view, then use the MR target branch as the code-review-specialists diff base.
   • Always run deterministic scope detection with forced minimum lenses:
     • review_specialists.py scope --base <mr-target-ref> --testing --maintainability
   • Do not skip specialist review only because the diff is small.
   • Add the shared risk lenses for security, API contract, data migration, performance, or red-team review when the MR scope warrants them.
   • Keep code-review-specialists read-only. Concrete findings are repaired by this delivery workflow on the MR branch, followed by validation, pipeline gates, and affected specialist review reruns.

6. Post delivery review outcome comment

   • Follow the shared delivery review outcome comment contract: skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md.
   • Use the shared disposition schema: skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_SCHEMA.md.
   • Render a compact MR comment with marker agent-kit:delivery-review-outcome:v1, review lenses, validation, pipeline status, and one row per meaningful review item.
   • Use dispositions fixed-now, accepted-residual, follow-up-linked, deferred-task, no-action, or blocked.
   • For fixed-now, the reason is optional but evidence and validation are required. For accepted-residual, follow-up-linked, deferred-task, and blocked, include the required reason and link or unblock evidence.
   • Post before merge:
     • glab mr note create <iid> < <comment.md>
   • If review blocks delivery, post a blocked outcome comment when possible, then stop before close with the exact unblock action.

7. Close MR

   • Run:
     • deliver-gitlab-mr.sh --kind <kind> close --mr <iid>
   • The close flow delegates to close-gitlab-mr and:
     • requires a clean working tree
     • runs after the mandatory specialist review gate has passed or has been explicitly accepted under the delivery review policy
     • runs after the delivery review outcome comment has been posted
     • marks draft MRs ready with glab mr update <iid> --ready --yes
     • merges with glab mr merge <iid> --yes
     • allows missing CI only when --allow-no-pipeline is explicitly supplied
     • does not remove the remote source branch unless --remove-source-branch is explicitly supplied
     • switches back to the target branch, fast-forwards from origin/<target>, and deletes the local source branch unless cleanup is disabled

8. Report delivery artifacts

   • Include MR URL/IID, pipeline status summary, specialist review lenses and outcome, delivery review outcome comment URL when available, merge result, target branch, and final branch state.

Completion Gate

• If there is no blocking error, this workflow must run end-to-end through close.
• Do not stop after create/open MR and report "next step is wait-pipeline/close".
• A stop before close is valid only when a real block/failure exists (for example: ambiguity confirmation pending, pipeline still failing, mandatory review findings pending decision, user-authorized review fixes still failing, timeout, auth/permission failure, non-mergeable MR, or explicit user pause).
• User-authorized review fixes are a delivery repair loop, not a successful stopping point.
• Closing an MR without merge is cleanup/abort, not successful delivery.
• When stopping before close, report status as BLOCKED or FAILED with the exact unblock action; do not report partial success.

Suspicious-Signal Matrix

Signal	Check rule	Risk level	Required handling
Cross-domain path spread	Changed paths span 2+ domains (app/product, infra/CI/tooling, docs/process) for a single-domain request.	medium	Inspect suspicious diffs before deciding scope.
Infra/tooling-only edits unrelated to request	Files are only infra/tooling paths (for example .gitlab-ci.yml, .github/, scripts/, skills/tools/, lockfiles) while request is app.	high	Inspect diffs; if request linkage is unclear, block and confirm.
Same-file staged+unstaged overlap	Any identical path appears in both staged and unstaged sets.	high	Always escalate to diff inspection; do not auto-pass triage.

Bypass Guidance

• Use --bypass-ambiguity (or --proceed-all) when:
  • preflight returns BLOCK_STATE=blocked_for_ambiguity
  • the user explicitly asks to continue despite ambiguity
  • the changed paths are confirmed in scope for the requested delivery
• Do not use bypass when:
  • branch guard fails
  • authentication/permission checks fail
  • pipeline fails or blocks
  • pipeline is missing and --allow-no-pipeline was not explicitly supplied
  • handling draft-state MRs
  • mergeability or project policy checks fail

Stop-And-Confirm Output Contract

• When preflight blocks for ambiguity, return a deterministic block payload and exit 1.
• Required fields:
  • BLOCK_STATE: must be blocked_for_ambiguity
  • CHANGE_STATE_SUMMARY: counts for staged, unstaged, untracked, and mixed_status=true|false
  • SUSPICIOUS_FILES: list of paths flagged by the suspicious-signal matrix
  • SUSPICIOUS_REASONS: one reason per suspicious file, mapped to matrix signal names
  • DIFF_INSPECTION_RESULT: per file classification in-scope|out-of-scope|uncertain
  • CONFIRMATION_PROMPT: explicit user action request to proceed or abort
  • NEXT_ACTION: must state "wait for user confirmation before continuing"

References

• Shared delivery specialist review gate: skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md
• Shared delivery review outcome comment: skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md