GitLab Access

Follow the current user request, role boundary, and approval policy. Loading this skill does not authorize an external mutation.

Use an isolated worktree, never the shared primary checkout

Before any git operation, create and operate in your own git worktree rather than the target project's shared primary checkout. Another agent may have uncommitted or staged work sitting there, and an unchecked checkout, reset, or clean can overwrite it even when your own command succeeds cleanly (→ RP-36). Remove your worktree when done; never assume the primary checkout's current branch or working-tree state matches what you last left it at.

Select the direct tool

• Use a configured GitLab MCP connector when available, or authenticated glab, for GitLab API work.
• Use Git directly for repository transport. Do not recreate a local commit through GitLab's commit API.
• If neither direct path works, report the blocker and request configuration or approval for the exact alternative. Do not switch to a browser, workflow platform, or another service's credential without explicit approval.

Check authentication first

Run glab auth status as the first command of any task that will use glab or Git transport for GitLab; an MCP-only task skips it. If it reports a failure, repeat it once as described under Protect authentication; if it still fails, stop and report the one decisive line to the coordinator or the user, and do not wait or continue to the next step with GitLab work pending (→ RP-51).

Protect authentication

An authentication check can fail when the current runtime cannot read the operating-system keyring. Use that runtime's documented permission mechanism to repeat the diagnostic before concluding that the user is signed out.

Never print, copy, or place an access token in a command, URL, log, or file.

When running in Codex, read references/codex.md before diagnosing authentication or using authenticated Git transport. Other runtimes do not load that reference.

Use authenticated HTTPS Git transport

Keep the glab credential helper local to each Git command. Never change repository, global, or system Git credential configuration.

For a push:

1. Derive the default target from the current local branch, validate it, derive the full remote ref, and record the intended commit. Stop if the repository is detached or the branch is empty, and keep the commit unchanged during the push and verification.

   gitlab_remote_branch="$(git branch --show-current)"
   test -n "$gitlab_remote_branch"
   git check-ref-format --branch "$gitlab_remote_branch"
   gitlab_remote_ref="refs/heads/$gitlab_remote_branch"
   git check-ref-format "$gitlab_remote_ref"
   gitlab_local_sha="$(git rev-parse HEAD)"

   For an explicitly different target, receive the branch name as data instead of inserting it into shell source. For example, use IFS= read -r gitlab_remote_branch, then run the same non-empty and git check-ref-format validations before deriving gitlab_remote_ref.

2. Push that exact commit with the refspec quoted as one argument:

   git -c credential.helper= \
     -c credential.helper='!glab auth git-credential' \
     push origin "${gitlab_local_sha}:${gitlab_remote_ref}"

3. Read the validated remote ref with the same command-scoped helper:

   git -c credential.helper= \
     -c credential.helper='!glab auth git-credential' \
     ls-remote --heads origin "$gitlab_remote_ref"

4. Report success only when the returned remote branch SHA exactly equals $gitlab_local_sha.

Apply the same command-scoped helper to other authenticated GitLab HTTPS transport commands. Use the current runtime's documented permission mechanism when keyring or network access requires it.

Read an MR's review state

Run python3 ${CLAUDE_PLUGIN_ROOT}/.claude/scripts/mr_state.py <project> <N> before starting a reviewer, an approval or a merge. Its last line NEXT is review, approval-only or merge-ready. approved: true from the approvals API is not evidence: a project with no approval rule returns it with an empty approved_by (→ RP-78).

Merge an MR

After a push to an already approved MR, glab mr approve can return 401 and register nothing; run glab mr unapprove, then approve (→ RP-28). /verify audits the GitLab approval object, not the note. Merge with glab mr merge <N> --sha <head> --squash --remove-source-branch, never a bare --yes, and confirm state: merged.

Check the remote before pushing to an existing branch

Run ls-remote --heads origin "$gitlab_remote_ref" first and compare the SHA with your local base. A remote SHA you did not push means another session wrote to the branch: stop, report it, and do not push or force until the owner confirms (→ RP-65).

Force-push after a rebase

After rebasing a branch already pushed to origin (e.g. onto a moved main), a plain push is rejected as non-fast-forward. Use --force-with-lease scoped to the exact prior remote SHA, so the push aborts instead of clobbering someone else's commit if the remote moved since you last fetched it:

gitlab_remote_branch="$(git branch --show-current)"
gitlab_prior_sha="<the remote SHA you rebased from, e.g. from your last fetch/push>"
git -c credential.helper= \
  -c credential.helper='!glab auth git-credential' \
  push --force-with-lease="${gitlab_remote_branch}:${gitlab_prior_sha}" origin "$gitlab_remote_branch"

After a force-push, run the ls-remote check and step 4 against the rebased commit.

zsh gotcha — always brace the variable before the colon. In zsh, $var:x is parsed as a parameter-expansion modifier (:a, :h, :t, :r, :e, :l, :u, :s, :q, :P, …), not a literal colon, whenever a modifier letter immediately follows the colon. --force-with-lease="$gitlab_remote_branch:$gitlab_prior_sha" silently mangles the branch name into garbage (e.g. :a runs an absolute-path transform) whenever the SHA happens to start with one of those letters, and the lease then matches nothing — git falls back to a plain non-fast-forward rejection that looks exactly like a stale-branch problem, not a quoting bug. Braces (${gitlab_remote_branch}:..., used above) make zsh treat the whole thing as one token and avoid this. Bash is unaffected either way, but always brace it since a script may run under either shell.

Verify with git push --dry-run first if you want to confirm the lease will apply without risking the actual push.

Upload a file to a project (MR screenshots)

Use --form to upload a file. Run the command inside the target repository so :id resolves. The token stays inside glab.

glab api --method POST projects/:id/uploads --form "file=@/path/to/shot.png"

The response has a markdown field. Paste it into the MR description or a note.

Do not use -F file=@<png>. It sends JSON, not multipart. GitLab answers HTTP 400 (glab 1.123).

Test with a throwaway file. An upload stays on the project.

Download an MR upload (screenshots)

Uploads need authentication, so a plain URL fails. Read the path /uploads/<secret>/<file> from the MR description or a note, then save it with glab api, run inside the target repository, and open the file with the Read tool.

glab api "projects/:id/uploads/<secret>/<file>" > "$scratch/<file>"