Skip to main content
Agent skill

Gitlab

Operate on GitLab projects, merge requests, pipelines, and repository contents through a GitLab account the user's team has bound to Nuphos. Nuphos backend hands out the binding's short-lived OAuth token; the agent talks to the GitLab API and clones or pushes over HTTPS directly. Use whenever the user asks about their GitLab repos, MRs, CI pipelines, wants code read from a GitLab repo, or asks to open/update/comment on merge requests.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Gitlab when an AI agent needs a reusable SKILL.md workflow for this job: Operate on GitLab projects, merge requests, pipelines, and repository contents through a GitLab account the user's team has bound to Nuphos. Nuphos backend hands out the binding's short-lived OAuth token; the agent talks to the GitLab API and clones or pushes over HTTPS directly. Use whenever the user asks about their GitLab repos, MRs, CI pipelines, wants code read from a GitLab repo, or asks to open/update/comment on merge requests.

When not to use it

Skip Gitlab when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/gitlab
# Save SKILL.md to ~/.claude/skills/gitlab/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/gitlab/SKILL.md. For a shared project, commit the folder at .claude/skills/gitlab/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Gitlab skill for this task: Use Gitlab when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# gitlab

## Session isolation

Keep CLI credentials and settings inside the current session's `HOME` (`NUPHOS_SESSION_HOME`) and respect the supplied CLI config environment variables. Do not copy another session's or the runtime owner's credentials. Without `NUPHOS_SESSION_HOME`, CLI defaults may use shared runtime configuration; be aware of the affected scope.

Changing runtime-global settings is possible, but strongly discouraged unless the user understands the impact on other sessions and explicitly requests it. Explain the shared scope first; do not unset session isolation variables, write to the runtime owner's home, use a shared OS credential store, or modify shared shell startup files as routine setup. This is configuration isolation, not an OS security boundary.

Use this skill when the user wants you to interact with GitLab on their behalf — list projects, inspect merge requests or CI pipelines, read repository files, clone a repo, push branches, or open/comment on MRs — using the **GitLab account** their team has bound to Nuphos. Works for gitlab.com and self-hosted GitLab alike.

Like the github skill, the backend hands the sandbox a **short-lived access token** (~2 h, auto-refreshed server-side; fetch again on 401). The GitLab connect dialog lets users choose scopes before authorizing. Its default selection requests read access plus `write_repository` and `api`, so you can read, clone, push branches, create/update merge requests, and post MR notes when the bound GitLab account itself has permission in the target project.

Older bindings may still have only `read_api read_user read_repository`. Check the `scope` returned by `/token` or printed by `setup-credentials.sh` before mutating. If the token lacks `api` or `write_repository`, ask a team admin to reconnect the GitLab account from the desktop app so Nuphos receives the newer write-capable grant.

## Setup

The bound GitLab accounts are already listed for you under **GitLab bindings:** in the credential section of the system prompt. Each line carries the `bindingId`, `hostUrl`, `username`, and a ready-to-run `setupCommand`. Pick the binding whose `hostUrl` matches the project the user is asking about and run its `setupCommand` verbatim:

```bash bash skills/gitlab/scripts/setup-credentials.sh <teamId> <bindingId> ```

It configures git + `glab` and writes `~/.gitlab-token` for raw API calls. Then:

```bash # Prefer the pre-installed GitLab CLI for common operations. glab repo list --member --output json

# Raw API fallback for endpoints glab does not expose directly. GITLAB_HOST="$(cat ~/.gitlab-host)" gl() { curl -sS -H @<(printf 'Authorization: Bearer %s\n' "$(cat ~/.gitlab-token)") "$GITLAB_HOST/api/v4$1" "${@:2}"; } ```

If the credential section lists no GitLab bindings, tell the user a team admin needs to connect a GitLab account first (desktop app → Integrations → Add → GitLab) — you cannot bind it for them because it requires an interactive OAuth grant in their browser.

### Fallback: discover bindings yourself

Only if the credential section is missing or looks stale. `$TEAM` is exported in the runtime environment.

```bash # Reuse the helper from the nuphos-api skill (loads it if needed): ac() { curl -sS -H @<(printf 'Authorization: Bearer %s\n' "$NUPHOS_TOKEN") "${NUPHOS_BACKEND_URL:-https://api.nuphos.ai}$1" "${@:2}"; }

ac /teams/$TEAM/gitlab-bindings | python3 -m json.tool # → { "bindings": [ { "id": "...", "hostUrl": "https://gitlab.com", "username": "...", ... } ] } ```

## Common operations

```bash # Prefer high-level commands: they handle host selection, authentication, # pagination, and JSON formatting without rebuilding API calls by hand. glab repo list --member --per-page 50 --output json glab mr list --repo <group/project> --per-page 30 --output json glab ci list --repo <group/project> --per-page 30 --output json glab mr view <iid> --repo <group/project> --comments

# Use the raw helper for an API shape without a glab command. # Projects the bound account can access, most recently active first. gl "/projects?membership=true&order_by=last_activity_at&per_page=50"

# Merge requests for a project (numeric id from the project list). gl "/projects/$PROJECT_ID/merge_requests?state=opened&per_page=30"

# One MR with diff stats; discussions/notes: gl "/projects/$PROJECT_ID/merge_requests/$MR_IID" gl "/projects/$PROJECT_ID/merge_requests/$MR_IID/notes?per_page=50"

# CI/CD pipelines + jobs: gl "/projects/$PROJECT_ID/pipelines?per_page=30" gl "/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs"

# Read a file without cloning (ref defaults to the default branch): gl "/projects/$PROJECT_ID/repository/files/path%2Fto%2Ffile?ref=main" | python3 -c ' import json,sys,base64; print(base64.b64decode(json.load(sys.stdin)["content"]).decode())'

# Clone — git credentials were set up by the script: git clone "$GITLAB_HOST/<group>/<project>.git"

# Push a branch after editing a cloned repo: git checkout -b my-change git push -u origin my-change

# Open an MR via API (requires the `api` scope and project permission): PROJECT_ID=<numeric project id> gl "/projects/$PROJECT_ID/merge_requests" \ -X POST \ --data-urlencode "source_branch=my-change" \ --data-urlencode "target_branch=main" \ --data-urlencode "title=fix: describe the change"

# Add a top-level MR note: MR_IID=<merge request iid> gl "/projects/$PROJECT_ID/merge_requests/$MR_IID/notes" \ -X POST \ --data-urlencode "body=Review note text" ```

The full GitLab REST API surface under `/api/v4` is available through the bound OAuth token. Prefer it over cloning when you only need metadata or a few files.

## Link work to the current conversation

After opening or adopting a merge request for the current task, call `bind_session_resource` when that native tool is available, with `provider: gitlab`, the selected `bindingId`, `project` (numeric id or full path) and the MR `iid`. The link shows the MR and its state in the session sidebar; it does not wake the conversation on MR events. Do not bind unrelated search results.

## Nuphos proxy fallback

The backend also proxies a small read-only subset — handy for a quick look without running setup. `/teams/$TEAM/gitlab-bindings/namespaces` (team-level, no binding id) flattens every top-level group/user namespace across all bindings with project counts; per binding there are `/teams/$TEAM/gitlab-bindings/$GB/projects?namespace=<root>`, `.../projects/:id/merge-requests`, and `.../projects/:id/pipelines`.

## Error handling

- `401` from GitLab — token expired; re-run `setup-credentials.sh`. If the backend's `/token` endpoint itself returns `401 gitlab_unauthorized`, the stored grant was revoked: tell the user to re-bind the GitLab account. - `403` on push/write with a token that lacks `api` or `write_repository` — old read-only binding; ask a team admin to reconnect GitLab from the desktop app. - `403` on push/write with `api`/`write_repository` present — the bound GitLab account itself lacks project permission; report the exact project and operation that failed. - `503 gitlab_oauth_not_configured` — backend operator issue, not fixable from the app.

Intended uses

  • Use Gitlab when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.