{"id":"8bc867e8-22e3-4fa3-9e09-04b0ad4e43c6","shortId":"BqjaVJ","kind":"skill","title":"gitlab-mr","tagline":"Create and manage GitLab Merge Requests on gitlab.example.com repositories, driving them to a truly mergeable state. Automatically generates User Story documentation, constructs MR descriptions (with blob links), pushes and creates MRs, polls CI pipeline status via API and fixes ","description":"# GitLab MR\n\nCreate an MR and drive it to a **truly mergeable** state (all CI green + no merge conflicts). Core principle: **write documentation first, then submit the MR, verify with APIs, and loop through fixes until the MR is mergeable.**\n\nPrerequisite: The current repository's remote points to `gitlab.example.com`, and `glab` CLI is installed.\n\n---\n\n## Rules\n\n1. **Never use the `skip-doc-check` label** — every MR must have a real documentation link\n2. **User Story must be relevant to the MR changes** — CI checks relevance (`check:mr-us-relevance`); irrelevant links will be rejected\n3. **Blob links must point to pushed files** — the branch name and file path in the link must exist on the remote\n4. **Verify with APIs, don't guess** — confirm results at every step using `glab` commands\n\n---\n\n## Execution Flow\n\n### Step 1: Check Prerequisites\n\n```bash\n# Confirm remote points to gitlab.example.com\ngit remote get-url origin\n\n# Confirm current branch is not main/master\ngit branch --show-current\n\n# Confirm no uncommitted changes\ngit status\n```\n\nIf there are uncommitted changes, commit or stash them first.\n\n### Step 2: Ensure Documentation Exists\n\nThe MR description must contain documentation links. CI performs two checks:\n- `check:mr-documentation`: whether the link format is valid\n- `check:mr-us-relevance`: whether the linked document is relevant to the MR changes\n\n**Prefer GitLab blob links** pointing to documentation files within the repository.\n\n#### 2a: Find or Create Documentation\n\nCheck whether related documentation already exists in the repository:\n\n```bash\n# Look for potentially related documents\nls docs/plans/ docs/04-user-stories/ 2>/dev/null\n```\n\nIf no related documentation exists, create one for this MR:\n\n- Place the document at `docs/plans/YYYY-MM-DD-<feature-name>.md` (design doc) or `docs/04-user-stories/<feature-name>.md` (User Story)\n- The document content must **cover the core changes in this MR** (otherwise the relevance check will fail)\n- The document does not need to be long, but must describe: what was done and why\n\n#### 2b: Commit and Push Documentation\n\n```bash\ngit add docs/plans/<doc-file>.md\ngit commit -m \"docs: add <feature> design document\"\n```\n\n### Step 3: Push the Branch\n\n```bash\ngit push -u origin <branch-name>\n```\n\n### Step 4: Create or Update MR\n\n#### Check if an MR already exists\n\n```bash\nglab mr list --source-branch <branch-name>\n```\n\n#### If no MR exists, create one\n\nAnalyze all commits in `git log main..HEAD` to write the MR title and description.\n\nBlob link format: `https://gitlab.example.com/<group>/<project>/-/blob/<branch>/<filepath>`\n\n- `<group>/<project>` parsed from `git remote get-url origin`\n- `<branch>` is the current branch name\n- `<filepath>` is the in-repo path to the document\n\n```bash\nglab mr create \\\n  --title \"<concise title, <70 chars>\" \\\n  --description \"$(cat <<'EOF'\n## Change Summary\n<Summary based on all commits, 2-3 bullet points>\n\n## Related Documentation\n- User Story (required): https://gitlab.example.com/<group>/<project>/-/blob/<branch>/docs/plans/<doc>.md\n- Tech Design: <fill if available, otherwise remove this line>\n\n## Change Type\n- [x] <corresponding type>\nEOF\n)\" \\\n  --push\n```\n\n#### If an MR exists but the description lacks documentation links\n\n```bash\nglab mr update <mr-id> --description \"$(cat <<'EOF'\n<complete description with blob links>\nEOF\n)\"\n```\n\n### Step 5: Wait and Check Pipeline\n\nAfter creating/updating the MR, wait for the pipeline to trigger and complete.\n\n```bash\n# Wait for pipeline to start (usually takes a few seconds after push)\nsleep 5\n\n# Check pipeline status\nglab ci status\n```\n\nIf the pipeline is still running, wait and check again:\n\n```bash\nsleep 20\nglab ci status\n```\n\n### Step 6: Handle Failed Jobs\n\nIf the pipeline fails, check which specific job failed:\n\n```bash\n# Get status of all jobs in the pipeline\nglab api \"projects/:id/merge_requests/<mr-iid>/pipelines\" | python3 -c \"\nimport sys,json\npipelines = json.load(sys.stdin)\nif pipelines:\n    pid = pipelines[0]['id']\n    print(f'Latest pipeline: {pid}, status: {pipelines[0][\\\"status\\\"]}')\n\"\n```\n\n```bash\n# View failed job logs\nglab api \"projects/:id/pipelines/<pipeline-id>/jobs\" | python3 -c \"\nimport sys,json\nfor j in json.load(sys.stdin):\n    if j['status'] == 'failed':\n        print(f'FAILED: {j[\\\"name\\\"]} (id={j[\\\"id\\\"]})')\n\"\n```\n\n```bash\n# Get the tail of a failed job's log\nglab api \"projects/:id/jobs/<job-id>/trace\" 2>&1 | tail -30\n```\n\n#### Common Failures and Fixes\n\n| Failed Job | Cause | Fix |\n|----------|------|---------|\n| `check:mr-documentation` | MR description missing a valid documentation link | `glab mr update <id> --description \"...\"` to add blob links |\n| `check:mr-us-relevance` | Document content is not relevant to MR changes | Edit the document to cover the MR's core changes, commit and push |\n| `validate:skills` | SKILL.md format is non-compliant | Run `uv run python scripts/validate.py --skills` to fix locally |\n| `validate:security` | Security scan detected an issue | Run `uv run python scripts/validate.py --security` to fix locally |\n| Merge conflict | Branch conflicts with main | `git fetch origin main && git rebase origin/main`, resolve conflicts and force push |\n\nAfter fixing:\n- If the issue was in the MR description (`check:mr-documentation`): update the description then retry the job\n- If the issue was in code/docs: commit the fix, push, and a new pipeline will trigger automatically\n\n```bash\n# Retry a failed job\nglab ci retry <job-id>\n\n# Or push a new commit to trigger a new pipeline\ngit push\n```\n\n### Step 7: Confirm MR Is Mergeable\n\nAfter CI passes, also confirm the MR has no merge conflicts. **CI passing does not mean mergeable.**\n\n```bash\nglab ci status        # Confirm CI is all green\nglab mr view <branch> # Confirm no merge conflict\n```\n\nIf there are merge conflicts, resolve them (rebase onto main), force push, and wait for the new CI to pass.\n\n**Loop through Steps 5-7 until both conditions are met: CI all green + no conflicts.**\n\nOnce the MR is truly mergeable, report the MR URL to the user.\n\n---\n\n## Examples\n\n### Full Workflow Example\n\n```\n# Create MR\nglab mr create --title \"feat: add retry logic\" --description \"...\" --push\n\n# Loop until CI passes\nglab ci status  # -> if failed, check logs, fix -> check again\n\n# After CI passes, check merge status\nglab mr view feat/add-retry-logic\n# -> conflicts? rebase to resolve -> force push -> wait for new CI\n\n# Final confirmation: CI all green + no conflicts -> report MR URL\n```\n\n---\n\n## Bad/Good Examples\n\n### Bad — Declaring done just because CI passed\n\n```\nglab ci status  # -> success\n# -> \"MR !42 is created, CI passed!\"  <- but there's actually a merge conflict, cannot merge\n```\n\n### Bad — Posting an irrelevant link\n\n```\nglab mr create --description \"User Story: .../README.md\"  # unrelated to changes, CI will reject\n```\n\n### Good — Driving to a truly mergeable state\n\n```\n# Create MR -> poll CI and fix failures -> check merge status -> resolve conflicts -> confirm mergeable\n```\n\n---\n\n## Notes\n\n- Branch names containing `/` (e.g., `feat/my-branch`) are correctly handled by GitLab in blob links\n- `glab ci status` shows the status of all jobs in the latest pipeline\n- If the pipeline doesn't trigger for a long time, you can manually run: `glab ci run`\n- After updating the MR description, you need to retry the failed job or wait for a new pipeline","tags":["gitlab","enterprise","harness","engineering","addxai","agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor","devops"],"capabilities":["skill","source-addxai","skill-gitlab-mr","topic-agent-skills","topic-ai-agent","topic-ai-engineering","topic-claude-code","topic-code-review","topic-cursor","topic-devops","topic-enterprise","topic-sre","topic-windsurf"],"categories":["enterprise-harness-engineering"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/addxai/enterprise-harness-engineering/gitlab-mr","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add addxai/enterprise-harness-engineering","source_repo":"https://github.com/addxai/enterprise-harness-engineering","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 16 github stars · SKILL.md body (7,389 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:02:11.838Z","embedding":null,"createdAt":"2026-04-21T19:04:01.359Z","updatedAt":"2026-04-22T01:02:11.838Z","lastSeenAt":"2026-04-22T01:02:11.838Z","tsv":"'-3':467 '-30':667 '-7':893 '/blob':424,476 '/dev/null':296 '/docs/plans':477 '/jobs':626 '/pipelines':593 '/readme.md':1016 '/trace':663 '0':606,615 '1':98,178,665 '2':115,221,295,466,664 '20':562 '2a':272 '2b':353 '3':138,371 '4':160,381 '42':991 '5':512,543,892 '6':567 '7':831 '70':454 'actual':999 'add':360,367,692,928 'alreadi':281,390 'also':839 'analyz':405 'api':40,73,163,590,623,660 'automat':20,809 'avail':483 'bad':979,1005 'bad/good':977 'base':462 'bash':181,286,358,375,392,447,503,529,560,580,617,649,810,853 'blob':29,139,263,420,693,1056 'branch':147,195,200,374,398,436,756,1045 'bullet':468 'c':595,628 'cannot':1003 'cat':457,508 'caus':674 'chang':124,207,214,260,327,459,488,707,717,1019 'char':455 'check':105,126,128,179,235,236,246,277,334,386,515,544,558,575,676,695,782,942,945,950,1037 'ci':36,57,125,232,548,564,816,837,847,855,858,886,899,935,938,948,966,969,984,987,994,1020,1033,1059,1086 'cli':94 'code/docs':798 'command':174 'commit':215,354,364,407,465,718,799,822 'common':668 'complet':528 'compliant':728 'concis':452 'condit':896 'confirm':167,182,193,204,832,840,857,865,968,1042 'conflict':61,755,757,768,846,868,873,903,957,973,1002,1041 'construct':25 'contain':229,1047 'content':322,701 'core':62,326,716 'correct':1051 'cover':324,712 'creat':4,33,45,275,302,382,403,450,921,925,993,1012,1030 'creating/updating':518 'current':85,194,203,435 'declar':980 'describ':347 'descript':27,227,419,456,499,507,681,690,781,788,931,1013,1092 'design':313,368,480 'detect':742 'doc':104,314,366 'docs/04-user-stories':294,316 'docs/plans':293,361 'docs/plans/yyyy-mm-dd-':311 'document':24,65,113,223,230,239,254,267,276,280,291,300,309,321,338,357,369,446,471,501,679,685,700,710,785 'doesn':1074 'done':350,981 'drive':13,49,1024 'e.g':1048 'edit':708 'ensur':222 'eof':458,491,509,510 'everi':107,170 'exampl':917,920,978 'execut':175 'exist':156,224,282,301,391,402,496 'f':609,642 'fail':336,569,574,579,619,640,643,655,672,813,941,1098 'failur':669,1036 'feat':927 'feat/add-retry-logic':956 'feat/my-branch':1049 'fetch':761 'file':145,150,268 'fill':481 'final':967 'find':273 'first':66,219 'fix':42,77,671,675,736,752,773,801,944,1035 'flow':176 'forc':770,879,961 'format':243,422,724 'full':918 'generat':21 'get':190,430,581,650 'get-url':189,429 'git':187,199,208,359,363,376,409,427,760,764,828 'gitlab':2,7,43,262,1054 'gitlab-mr':1 'gitlab.example.com':11,91,186,423,475 'glab':93,173,393,448,504,547,563,589,622,659,687,815,854,862,923,937,953,986,1010,1058,1085 'good':1023 'green':58,861,901,971 'guess':166 'handl':568,1052 'head':412 'id':607,646,648 'id/jobs':662 'id/merge_requests':592 'id/pipelines':625 'import':596,629 'in-repo':440 'instal':96 'irrelev':133,1008 'issu':744,776,795 'j':633,638,644,647 'job':570,578,585,620,656,673,792,814,1066,1099 'json':598,631 'json.load':600,635 'label':106 'lack':500 'latest':610,1069 'line':487 'link':30,114,134,140,154,231,242,253,264,421,502,686,694,1009,1057 'list':395 'local':737,753 'log':410,621,658,943 'logic':930 'long':344,1079 'look':287 'loop':75,889,933 'ls':292 'm':365 'main':411,759,763,878 'main/master':198 'manag':6 'manual':1083 'md':312,317,362,478 'mean':851 'merg':8,60,754,845,867,872,951,1001,1004,1038 'mergeabl':18,54,82,835,852,909,1028,1043 'met':898 'miss':682 'mr':3,26,44,47,70,80,108,123,130,226,238,248,259,306,330,385,389,394,401,416,449,495,505,520,678,680,688,697,706,714,780,784,833,842,863,906,912,922,924,954,975,990,1011,1031,1091 'mr-document':237,677,783 'mr-us-relev':129,247,696 'mrs':34 'must':109,118,141,155,228,323,346 'name':148,437,645,1046 'need':341,1094 'never':99 'new':805,821,826,885,965,1104 'non':727 'non-compli':726 'note':1044 'one':303,404 'onto':877 'origin':192,379,432,762 'origin/main':766 'otherwis':331,484 'pars':425 'pass':838,848,888,936,949,985,995 'path':151,443 'perform':233 'pid':604,612 'pipelin':37,516,524,532,545,552,573,588,599,603,605,611,614,806,827,1070,1073,1105 'place':307 'point':89,142,184,265,469 'poll':35,1032 'post':1006 'potenti':289 'prefer':261 'prerequisit':83,180 'principl':63 'print':608,641 'project':591,624,661 'push':31,144,356,372,377,492,541,720,771,802,819,829,880,932,962 'python':732,748 'python3':594,627 'real':112 'rebas':765,876,958 'reject':137,1022 'relat':279,290,299,470 'relev':120,127,132,250,256,333,699,704 'remot':88,159,183,188,428 'remov':485 'repo':442 'report':910,974 'repositori':12,86,271,285 'request':9 'requir':474 'resolv':767,874,960,1040 'result':168 'retri':790,811,817,929,1096 'rule':97 'run':555,729,731,745,747,1084,1087 'scan':741 'scripts/validate.py':733,749 'second':539 'secur':739,740,750 'show':202,1061 'show-curr':201 'skill':722,734 'skill-gitlab-mr' 'skill.md':723 'skip':103 'skip-doc-check':102 'sleep':542,561 'sourc':397 'source-addxai' 'source-branch':396 'specif':577 'start':534 'stash':217 'state':19,55,1029 'status':38,209,546,549,565,582,613,616,639,856,939,952,988,1039,1060,1063 'step':171,177,220,370,380,511,566,830,891 'still':554 'stori':23,117,319,473,1015 'submit':68 'success':989 'summari':460,461 'sys':597,630 'sys.stdin':601,636 'tail':652,666 'take':536 'tech':479 'time':1080 'titl':417,451,453,926 'topic-agent-skills' 'topic-ai-agent' 'topic-ai-engineering' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-devops' 'topic-enterprise' 'topic-sre' 'topic-windsurf' 'trigger':526,808,824,1076 'truli':17,53,908,1027 'two':234 'type':489 'u':378 'uncommit':206,213 'unrel':1017 'updat':384,506,689,786,1089 'url':191,431,913,976 'us':131,249,698 'use':100,172 'user':22,116,318,472,916,1014 'usual':535 'uv':730,746 'valid':245,684,721,738 'verifi':71,161 'via':39 'view':618,864,955 'wait':513,521,530,556,882,963,1101 'whether':240,251,278 'within':269 'workflow':919 'write':64,414 'x':490","prices":[{"id":"63b85649-bcae-4394-9b57-40ba8d0f50ba","listingId":"8bc867e8-22e3-4fa3-9e09-04b0ad4e43c6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"addxai","category":"enterprise-harness-engineering","install_from":"skills.sh"},"createdAt":"2026-04-21T19:04:01.359Z"}],"sources":[{"listingId":"8bc867e8-22e3-4fa3-9e09-04b0ad4e43c6","source":"github","sourceId":"addxai/enterprise-harness-engineering/gitlab-mr","sourceUrl":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/gitlab-mr","isPrimary":false,"firstSeenAt":"2026-04-21T19:04:01.359Z","lastSeenAt":"2026-04-22T01:02:11.838Z"}],"details":{"listingId":"8bc867e8-22e3-4fa3-9e09-04b0ad4e43c6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"addxai","slug":"gitlab-mr","github":{"repo":"addxai/enterprise-harness-engineering","stars":16,"topics":["agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor","devops","enterprise","sre","windsurf"],"license":"apache-2.0","html_url":"https://github.com/addxai/enterprise-harness-engineering","pushed_at":"2026-04-17T08:57:37Z","description":"Enterprise-grade AI Agent Skills for software development, DevOps, SRE, security, and product teams. Compatible with Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, and 30+ AI coding agents.","skill_md_sha":"7ce3ee9c57255e8a7a673e65879200241018cec6","skill_md_path":"skills/gitlab-mr/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/gitlab-mr"},"layout":"multi","source":"github","category":"enterprise-harness-engineering","frontmatter":{"name":"gitlab-mr","description":"Create and manage GitLab Merge Requests on gitlab.example.com repositories, driving them to a truly mergeable state. Automatically generates User Story documentation, constructs MR descriptions (with blob links), pushes and creates MRs, polls CI pipeline status via API and fixes failures, resolves merge conflicts, and loops until all MR checks pass with no conflicts. Triggers when the user says \"submit MR\", \"create MR\", \"push and create MR\", \"merge to main\", or needs to submit the current branch for review."},"skills_sh_url":"https://skills.sh/addxai/enterprise-harness-engineering/gitlab-mr"},"updatedAt":"2026-04-22T01:02:11.838Z"}}