GitLab Config

Do this once. Every other skill reads from the same config — get it right here and everything else just works.

Install

pip install requests
# or
pip install -r ~/.claude/skills/gitlab-config/requirements.txt

Configure

cp ~/.claude/skills/gitlab-config/gitlab_config.json.template ~/.gitlab/config.json
chmod 600 ~/.gitlab/config.json

Edit ~/.gitlab/config.json:

{
  "default": "work",
  "instances": {
    "work": {
      "url": "https://gitlab.company.com",
      "token": "glpat-xxxxxxxxxxxxxxxxxxxx"
    },
    "personal": {
      "url": "https://gitlab.com",
      "token": "glpat-yyyyyyyyyyyyyyyyyyyy"
    }
  },
  "projects": {
    "webapp": {
      "project_id": "acme/webapp",
      "instance": "work"
    }
  }
}

Get a token: GitLab → Settings → Access Tokens — create with api scope. It won't be shown again.

Env var fallback (single instance only):

export GITLAB_URL="https://gitlab.com"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Verify

python ~/.claude/skills/gitlab-config/scripts/gitlab_api.py list-instances
python ~/.claude/skills/gitlab-config/scripts/gitlab_api.py list-projects

API reference

All other skills use these scripts:

GITLAB="$HOME/.claude/skills/gitlab-config/scripts/gitlab_api.py"

# Issues
python $GITLAB get-issue <project> <issue_iid>
python $GITLAB list-issues <project> [state] [labels...]
python $GITLAB post-issue-comment <project> <issue_iid> "<comment>"

# Merge Requests
python $GITLAB get-mr <project> <mr_iid>
python $GITLAB list-mrs <project> [state]
python $GITLAB get-diff <project> <mr_iid>
python $GITLAB post-mr-comment <project> <mr_iid> "<comment>"

# Stats
python $GITLAB aggregate-issues <project> [days]

# Override instance for a single call
python $GITLAB --instance=personal get-issue blog 42

<project> accepts: alias (webapp), numeric ID (123), or full path (acme/webapp).

Config lookup order: ./gitlab_config.json → ~/.gitlab/config.json → skill directory.

Instance resolution: --instance flag → project's configured instance → default.

Local memory (instance / group / project / issue cache)

Every other skill should prefer these over the plain get-issue/get-project calls above — they hit the API the same way, but merge the result into ~/.gitlab/cache/<instance>/... instead of throwing it away. Nothing already cached is ever dropped; new data layers on top.

python $GITLAB sync-project <project>              # project metadata + team roster -> project.json, feeds users.json
                                                    # also syncs the project's parent group, if it has one
python $GITLAB sync-group <group_path>             # group metadata + members -> group.json, feeds users.json
python $GITLAB sync-issue <project> <issue_iid>     # issue + notes, merged by note id -> issues/<iid>.json
python $GITLAB cached-issue <project> <issue_iid>   # read the cache with no network call

CACHE="$HOME/.claude/skills/gitlab-config/scripts/gitlab_cache.py"
python $CACHE get-users <instance>                            # instance-level team/user directory
python $CACHE get-group <instance> <group_path>               # group-level metadata + members
python $CACHE get-project <instance> <project_id>              # project-level metadata
python $CACHE annotate-issue <instance> <project_id> <issue_iid> <key> <value>     # record analysis/notes against an issue
python $CACHE annotate-project <instance> <project_id> <key> <value>               # record project-wide memory

Why this exists: analysis, triage, and reply-drafting all re-read the same issue and the same team roster repeatedly. sync-issue still calls the API every time (so new comments are never missed) but merges onto the cached copy — so your own annotations (root cause, which comments you've already handled) survive, and you're not re-deriving what you already knew. sync-project builds the team directory once so usernames resolve to real names without a separate lookup per comment.

A GitLab group can hold several projects — e.g. group acme/rocket holds projects rocket-web and rocket-mobile. sync-project automatically syncs the parent group too (detected from the project's namespace), so the group's roster and metadata are fetched once and shared across every project under it instead of being duplicated per project.

Cache layout:

~/.gitlab/cache/<instance>/users.json                              # instance-level: every user seen, keyed by id
~/.gitlab/cache/<instance>/groups/<group>/group.json               # group-level: metadata + members, shared by its projects
~/.gitlab/cache/<instance>/projects/<project>/project.json         # project-level: metadata, members, and your own `_memory`
~/.gitlab/cache/<instance>/projects/<project>/issues/<iid>.json    # issue-level: issue + notes + your own `_notes` annotations

Troubleshooting