setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Set up GitLab MR Guardian

1. Show the currently effective configuration and monitor switch:

   ```bash
   "${CLAUDE_PLUGIN_ROOT}/bin/gitlab-mr-guardian" \
     --plugin-data-dir "${CLAUDE_PLUGIN_DATA}" \
     configure
   ```

   The `CONFIG_SHOW` output includes `config` (effective values) and `monitor_enabled` (the real persistent background-polling switch).

2. Determine the GitLab hostname: use `$ARGUMENTS` when supplied; otherwise keep the already-configured hostname when it is non-empty; otherwise infer it from `git remote get-url origin`; otherwise ask the user.

3. Run `glab auth status --hostname <hostname>`. If it reports a token problem, do not stop there: confirm with a real read call such as `glab api user --hostname <hostname>`, because `glab auth status` can report an invalid token while API access still works. Never print or request an access token when `glab` API calls succeed. Warn the user that write operations (rebase, pipeline trigger, auto-merge) may still fail if the token lacks `api` scope.

4. Explain the two mutation switches: `auto_rebase` is on by default and rewrites the source branch, but only when GitLab reports `need_rebase` and the MR is managed (offer `--auto-rebase false` to users who do not want it). Note that a rebase is allowed by default even when it clears existing approvals, because a managed MR has already been reviewed; mention `--allow-rebase-that-resets-approvals false` to anyone who needs those approvals preserved. `auto_merge` is off by default and can merge code immediately once all guarded checks pass; obtain confirmation before enabling it unless the user already explicitly requested it in the current turn.

5. Persist the configuration into the plugin data directory. Pass only the options the user chose to set; omitted options keep their previous or default values:

   ```bash
   "${CLAUDE_PLUGIN_ROOT}/bin/gitlab-mr-guardian" \
     --plugin-data-dir "${CLAUDE_PLUGIN_DATA}" \
     configure \
     --hostname "<hostname>"
   ```

   This writes `settings.json` inside `${CLAUDE_PLUGIN_DATA}`. The background monitor and all other commands read configuration from this file; native plugin userConfig substitution is not used. Never create or edit configuration inside the user's repository.

   Blocker-clearing rules are on by default, because a managed MR has already passed human review: `max_pipeline_retries` (retry a failed pipeline's jobs up to 10 times, one attempt per polling cycle), `rebase_when_ci_failed` (allow safe rebase for `need_rebase` MRs while CI is not yet successful — failed, running, missing, or skipped; a running pipeline on the stale base is superseded), `allow_rebase_that_resets_approvals` and `allow_rebase_when_approval_policy_unknown` (rebase even when it would clear approvals or the approval policy cannot be read). Turn any of them off with `--<flag> false` when the user wants a more conservative posture — for example `--allow-rebase-that-resets-approvals false` to preserve approvals.

   Optional extensions that are off by default: `--require-successful-pipeline-history true` (restrict management to approved MRs whose history already shows a successful pipeline; by default approval alone is enough) and `--advisory-reviewers <bot,names>` (comma-separated usernames, e.g. AI review bots, whose unresolved discussions are advisory and never block automation). Explain the behavior change and confirm before enabling either unless the user already explicitly requested it.

   Polling visibility: quiet cycles report a `MONITOR_HEARTBEAT` by default, so a silent Monitor is distinguishable from a dead one. Every heartbeat wakes the session, so when the user sets a short `poll_interval_seconds`, point out `--heartbeat-min-interval-seconds <seconds>` to throttle idle reports (real events always report immediately regardless), or `--heartbeat-when-idle false` to silence them entirely and rely on `monitor.last_cycle` in `status`.

6. Run a read-only status check and summarize which merge requests are monitored, paused for review, waiting for CI, or blocked:

   ```bash
   "${CLAUDE_PLUGIN_ROOT}/bin/gitlab-mr-guardian" \
     --plugin-data-dir "${CLAUDE_PLUGIN_DATA}" \
     status
   ```

7. Report the real monitoring state from the `monitor_enabled` field of the `CONFIG_SAVED` output — do not assume polling is off. If it is `true`, background polling is already active and will pick up the new configuration on its next cycle. If it is `false`, tell the user that `/gitlab-mr-guardian:start` enables background polling and `/gitlab-mr-guardian:stop` disables it; polling runs only while an interactive Claude Code session is open.

Do not weaken the approval or unresolved-discussion checks — those still gate every mutation. `allow_rebase_that_resets_approvals` is on by default, so tell the user a rebase can invalidate approvals and set it to `false` when they want them preserved.

From MisterRaindrop/gitlab-mr-guardian, Apache-2.0.

More from MisterRaindrop/gitlab-mr-guardian