亚特实验室先生
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
如果有未提交的更改,请先提交或隐藏它们。
MR 描述必须包含文档链接。 CI 执行两项检查: `check:mr-documentation`:链接格式是否有效 `check:mr-us-relevance`:链接文档是否与 MR 更改相关 首选指向存储库中文档文件的 GitLab blob 链接。 2a:查找或创建文档
检查是否已存在 MR 如果不存在,则创建一个 分析`git log main..HEAD` 中的所有提交,写入 MR 标题和描述。 Blob 链接格式:从 `git remote get-url origin` 解析出的 `https://gitlab.example.com/<group>/<project>/-/blob/<branch>/<filepath>` `<group>/<project>`
创建/更新 MR 后,等待管道触发并完成。如果管道仍在运行,请等待并再次检查:
如果管道失败,请检查哪个特定作业失败: 常见故障和修复 失败作业 · 原因 · 修复 `check:mr-documentation` · MR 描述缺少有效的文档链接 · `glab mr update <id> --description "..."` 添加 blob 链接 `check:mr-us-relevance` · 文档内容与 MR 更改不相关 · 编辑文档以涵盖 MR 的核心更改,提交并推送
CI通过后,还要确认MR没有合并冲突。 CI 通过并不意味着可合并。如果存在合并冲突,请解决它们(rebase to main),强制推送,并等待新的 CI 通过。循环执行步骤 5-7,直到满足两个条件:CI 全绿色 + 无冲突。一旦 MR 真正可合并,请将 MR URL 报告给用户。
# GitLab MR
Create 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.**
Prerequisite: The current repository's remote points to `gitlab.example.com`, and `glab` CLI is installed.
---
## Rules
1. **Never use the `skip-doc-check` label** — every MR must have a real documentation link
2. **User Story must be relevant to the MR changes** — CI checks relevance (`check:mr-us-relevance`); irrelevant links will be rejected
3. **Blob links must point to pushed files** — the branch name and file path in the link must exist on the remote
4. **Verify with APIs, don't guess** — confirm results at every step using `glab` commands
---
## Execution Flow
### Step 1: Check Prerequisites
```bash
# Confirm remote points to gitlab.example.com
git remote get-url origin
# Confirm current branch is not main/master
git branch --show-current
# Confirm no uncommitted changes
git status
```
If there are uncommitted changes, commit or stash them first.
### Step 2: Ensure Documentation Exists
The MR description must contain documentation links. CI performs two checks:
- `check:mr-documentation`: whether the link format is valid
- `check:mr-us-relevance`: whether the linked document is relevant to the MR changes
**Prefer GitLab blob links** pointing to documentation files within the repository.
#### 2a: Find or Create Documentation
Check whether related documentation already exists in the repository:
```bash
# Look for potentially related documents
ls docs/plans/ docs/04-user-stories/ 2>/dev/null
```
If no related documentation exists, create one for this MR:
- Place the document at `docs/plans/YYYY-MM-DD-<feature-name>.md` (design doc) or `docs/04-user-stories/<feature-name>.md` (User Story)
- The document content must **cover the core changes in this MR** (otherwise the relevance check will fail)
- The document does not need to be long, but must describe: what was done and why
#### 2b: Commit and Push Documentation
```bash
git add docs/plans/<doc-file>.md
git commit -m "docs: add <feature> design document"
```
### Step 3: Push the Branch
```bash
git push -u origin <branch-name>
```
### Step 4: Create or Update MR
#### Check if an MR already exists
```bash
glab mr list --source-branch <branch-name>
```
#### If no MR exists, create one
Analyze all commits in `git log main..HEAD` to write the MR title and description.
Blob link format: `https://gitlab.example.com/<group>/<project>/-/blob/<branch>/<filepath>`
- `<group>/<project>` parsed from `git remote get-url origin`
- `<branch>` is the current branch name
- `<filepath>` is the in-repo path to the document
```bash
glab mr create \
--title "<concise title, <70 chars>" \
--description "$(cat <<'EOF'
## Change Summary
<Summary based on all commits, 2-3 bullet points>
## Related Documentation
- User Story (required): https://gitlab.example.com/<group>/<project>/-/blob/<branch>/docs/plans/<doc>.md
- Tech Design: <fill if available, otherwise remove this line>
## Change Type
- [x] <corresponding type>
EOF
)" \
--push
```
#### If an MR exists but the description lacks documentation links
```bash
glab mr update <mr-id> --description "$(cat <<'EOF'
<complete description with blob links>
EOF
)"
```
### Step 5: Wait and Check Pipeline
After creating/updating the MR, wait for the pipeline to trigger and complete.
```bash
# Wait for pipeline to start (usually takes a few seconds after push)
sleep 5
# Check pipeline status
glab ci status
```
If the pipeline is still running, wait and check again:
```bash
sleep 20
glab ci status
```
### Step 6: Handle Failed Jobs
If the pipeline fails, check which specific job failed:
```bash
# Get status of all jobs in the pipeline
glab api "projects/:id/merge_requests/<mr-iid>/pipelines" | python3 -c "
import sys,json
pipelines = json.load(sys.stdin)
if pipelines:
pid = pipelines[0]['id']
print(f'Latest pipeline: {pid}, status: {pipelines[0][\"status\"]}')
"
```
```bash
# View failed job logs
glab api "projects/:id/pipelines/<pipeline-id>/jobs" | python3 -c "
import sys,json
for j in json.load(sys.stdin):
if j['status'] == 'failed':
print(f'FAILED: {j[\"name\"]} (id={j[\"id\"]})')
"
```
```bash
# Get the tail of a failed job's log
glab api "projects/:id/jobs/<job-id>/trace" 2>&1 | tail -30
```
#### Common Failures and Fixes
| Failed Job | Cause | Fix |
|----------|------|---------|
| `check:mr-documentation` | MR description missing a valid documentation link | `glab mr update <id> --description "..."` to add blob links |
| `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 |
| `validate:skills` | SKILL.md format is non-compliant | Run `uv run python scripts/validate.py --skills` to fix locally |
| `validate:security` | Security scan detected an issue | Run `uv run python scripts/validate.py --security` to fix locally |
| Merge conflict | Branch conflicts with main | `git fetch origin main && git rebase origin/main`, resolve conflicts and force push |
After fixing:
- If the issue was in the MR description (`check:mr-documentation`): update the description then retry the job
- If the issue was in code/docs: commit the fix, push, and a new pipeline will trigger automatically
```bash
# Retry a failed job
glab ci retry <job-id>
# Or push a new commit to trigger a new pipeline
git push
```
### Step 7: Confirm MR Is Mergeable
After CI passes, also confirm the MR has no merge conflicts. **CI passing does not mean mergeable.**
```bash
glab ci status # Confirm CI is all green
glab mr view <branch> # Confirm no merge conflict
```
If there are merge conflicts, resolve them (rebase onto main), force push, and wait for the new CI to pass.
**Loop through Steps 5-7 until both conditions are met: CI all green + no conflicts.**
Once the MR is truly mergeable, report the MR URL to the user.
---
## Examples
### Full Workflow Example
```
# Create MR
glab mr create --title "feat: add retry logic" --description "..." --push
# Loop until CI passes
glab ci status # -> if failed, check logs, fix -> check again
# After CI passes, check merge status
glab mr view feat/add-retry-logic
# -> conflicts? rebase to resolve -> force push -> wait for new CI
# Final confirmation: CI all green + no conflicts -> report MR URL
```
---
## Bad/Good Examples
### Bad — Declaring done just because CI passed
```
glab ci status # -> success
# -> "MR !42 is created, CI passed!" <- but there's actually a merge conflict, cannot merge
```
### Bad — Posting an irrelevant link
```
glab mr create --description "User Story: .../README.md" # unrelated to changes, CI will reject
```
### Good — Driving to a truly mergeable state
```
# Create MR -> poll CI and fix failures -> check merge status -> resolve conflicts -> confirm mergeable
```
---
## Notes
- Branch names containing `/` (e.g., `feat/my-branch`) are correctly handled by GitLab in blob links
- `glab ci status` shows the status of all jobs in the latest pipeline
- If the pipeline doesn't trigger for a long time, you can manually run: `glab ci run`
- After updating the MR description, you need to retry the failed job or wait for a new pipeline
---
> Source: [addxai/enterprise-harness-engineering](https://github.com/addxai/enterprise-harness-engineering) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
按说明文件中的顺序排列。
规则
第 1 步:检查先决条件
第 2 步:确保文档存在
步骤 4:创建或更新 MR
第 5 步:等待并检查管道
文件/命令 -> gitlab.example.com · glab · skip-doc-check · check:mr-us-relevance · check:mr-documentation · docs/plans/YYYY-MM-DD-<feature-name>.md · docs/04-user-stories/<feature-name>.md · git log main..HEAD
内容校验值 -> ac33f8e836b7
当前原文的自动摘译,尚未人工审校。
规则
切勿使用
skip-doc-check标签 — 每个 MR 必须有真实的文档链接 用户故事必须与 MR 更改相关 — CI 检查相关性 (check:mr-us-relevance);不相关的链接将被拒绝 Blob 链接必须指向推送的文件 - 链接中的分支名称和文件路径必须存在于远程 通过 API 进行验证,不要猜测 - 使用glab命令确认每一步的结果步骤 4:创建或更新 MR
检查是否已存在 MR 如果不存在,则创建一个 分析
git log main..HEAD中的所有提交,写入 MR 标题和描述。 Blob 链接格式:从git remote get-url origin解析出https://gitlab.example.com/<group>/<project>/-/blob/<branch>/<filepath><group>/<project>