mrstack

mrstack is a Go CLI for discovering, checking, and safely restacking a strict linear chain of ordinary GitLab merge requests. It targets Agoda's GitLab 18.11 deployment while retaining useful restack, CI-evidence, history, and agent-integration behavior after GitLab 19.1 native stacks arrive.

Given a chain such as:

main <── feature-a <── feature-b <── feature-c
         MR !101        MR !102        MR !103

mrstack derives the chain from GitLab, checks exact ancestry and CI, rewrites only the stale suffix in an isolated worktree, and publishes every affected branch atomically with explicit leases. It never merges MRs, silently resolves conflicts, or guesses after an uncertain push.

Start with the complete user guide.

Canonical source: github.com/nkaewam/mrstack. CI/CD and release automation use GitHub Actions; runtime GitLab access remains local through glab.

Installation

mrstack is a single CGO-free Go binary. Prebuilt archives are published for macOS and Linux on AMD64 and ARM64. Git and an authenticated glab are required at runtime.

Homebrew (recommended)

Install the appropriate prebuilt release binary from the nkaewam/tap tap:

brew install nkaewam/tap/mrstack

Go is not required. To upgrade later:

brew update
brew upgrade mrstack

Verify that the executable is available:

command -v mrstack

GitHub Releases

Without Homebrew, download and verify the archive for the current operating system and CPU architecture from GitHub Releases. Set VERSION to the release tag to install:

VERSION=v0.1.0
case "$(uname -s)" in
  Darwin) os=darwin ;;
  Linux)  os=linux  ;;
esac
case "$(uname -m)" in
  arm64|aarch64) arch=arm64 ;;
  x86_64|amd64)   arch=amd64 ;;
esac
curl -LO "https://github.com/nkaewam/mrstack/releases/download/${VERSION}/mrstack_${VERSION#v}_${os}_${arch}.tar.gz"
tar -xzf "mrstack_${VERSION#v}_${os}_${arch}.tar.gz"
install -m 0755 "mrstack_${VERSION#v}_${os}_${arch}/mrstack" /usr/local/bin/mrstack

Agent Skill

mrstack ships an Agent Skill that teaches coding agents how to operate mrstack in machine mode — the check → restack → recheck loop, interpreting dispositions/findings, executing remediation actions verbatim, and honoring the safety invariants.

Install it with the Vercel Skills CLI (works with Cursor, Claude Code, Codex, Copilot, Goose, OpenCode, and 18+ other agents):

npx skills add nkaewam/mrstack

Install globally (available in every project):

npx skills add nkaewam/mrstack -g

Target a specific agent, or skip prompts in CI:

npx skills add nkaewam/mrstack -a cursor
npx skills add nkaewam/mrstack -g -y

Browse skills at skills.sh. The skill source lives at skills/mrstack/ and validates against the Agent Skills spec.

Quick start

Go 1.24 or newer, Task 3, git, and an authenticated glab are required.

task build
cd /path/to/your/gitlab-project
/path/to/mrstack/bin/mrstack doctor
/path/to/mrstack/bin/mrstack check

Select a stack by current branch, MR IID, or branch name:

mrstack check
mrstack check 102
mrstack check feature-b

If a check reports needs_restack, use the exact returned snapshot:

mrstack restack 102 --snapshot <snapshot-id>

For agents and scripts, pair --json with --no-input; mutating commands also require --yes:

mrstack --json --no-input --remote origin check 102
mrstack --json --no-input --yes --remote origin \
  restack 102 --snapshot <snapshot-id>

Design documents

• V1 design
• User guide
• CLI contract
• Agent JSON API
• Agent API JSON Schema
• Acceptance contract
• Testing guide
• GitHub Actions CI/CD contract
• Domain language
• Architecture decisions

Core rule

GitLab MR source and target branch relationships are the sole source of truth for live stack membership and order. The local journal records history and durable operation recovery but never defines the chain.

Build and test

task build
task test
task test-race

The binary is written to bin/mrstack. All GitLab access goes through the caller's existing glab authentication; mrstack does not store a GitLab token.