fgcz-gitlab

FGCZ GitLab Management

Use the glab CLI to manage issues, merge requests, CI/CD pipelines, and projects on FGCZ's self-hosted GitLab at gitlab.bfabric.org.

Setup

Just run glab commands directly — no upfront check needed. glab auto-detects the correct host from git remotes.

If a command fails with an authentication or host error, run the diagnostic script:

bash SKILL_DIR/scripts/check_glab_setup.sh

If glab is not installed

Tell the user: brew install glab (macOS) or download from https://gitlab.com/gitlab-org/cli/-/releases

If not authenticated for gitlab.bfabric.org

OAuth is not available on this self-hosted instance (it requires a registered GitLab app). Tell the user to run these commands themselves in a terminal — do not run them from Claude Code as they involve secrets:

1. Create a Personal Access Token at https://gitlab.bfabric.org/-/user_settings/personal_access_tokens (scopes: api, write_repository, read_repository)
2. Authenticate: glab auth login --hostname gitlab.bfabric.org --token glpat-XXXXX

Stop and wait for the user to confirm they've completed setup before running any glab commands. Never fall back to web fetching or curl — the user needs a working glab setup for ongoing use.

Working with gitlab.bfabric.org URLs

When the user shares a URL like https://gitlab.bfabric.org/group/project/-/issues/42 or https://gitlab.bfabric.org/group/project/-/work_items/30:

• glab issue view accepts full URLs directly: glab issue view https://gitlab.bfabric.org/group/project/-/issues/42
• For work_items URLs (/-/work_items/N), extract the repo and ID and use: glab issue view N -R group/project
• When not inside the repo directory, always pass -R group/project

Workflow: Fix an Issue from a URL

This is the most common workflow — the user shares a gitlab.bfabric.org issue link and asks to fix it.

1. Fetch the issue to understand what needs to be done:

   glab issue view <id> -R group/project --comments
   

2. Clone the repo if not already in it:

   glab repo clone group/project && cd project
   

3. Create a branch, make changes, push:

   git checkout -b fix/issue-<id>-short-description
   # ... make changes ...
   git push -u origin fix/issue-<id>-short-description
   

4. Create a merge request:

   glab mr create --fill --target-branch main
   

   If you need a custom title/description instead of --fill, use a heredoc for multi-line markdown content:

   glab mr create \
     --target-branch main \
     --title "Fix issue #<id>: short description" \
     --description "$(cat <<'EOF'
   ## Summary
   
   Closes #<id>
   
   - First change
   - Second change
   
   ## Testing
   
   - Ran unit tests
   EOF
   )"
   

Issues

glab issue list                                    # list open issues
glab issue list --assignee=@me                     # your issues
glab issue list --label=bug --milestone="v1.0"     # filtered
glab issue view <id>                               # view details
glab issue view <id> --comments                    # with comments
glab issue create --title "..." --description "..."
glab issue close <id>
glab issue reopen <id>
glab issue note <id> -m "Comment text"             # add comment

When not inside the target repo, add -R group/project to any command.

Merge Requests

glab mr list                                       # list open MRs
glab mr list --assignee=@me                        # your MRs
glab mr list --reviewer=@me                        # MRs to review
glab mr view <id>                                  # view details
glab mr view <id> --comments                       # with comments/discussions
glab mr diff <id>                                  # view diff
glab mr create --fill --target-branch main         # from current branch
glab mr create --fill --draft --target-branch main # draft MR
glab mr create --related-issue <issue-id> --fill   # MR linked to issue
glab mr approve <id>
glab mr merge <id>
glab mr note <id> -m "Review comment"              # add comment

Workflow: Pending Code Review with Draft Notes

For multi-comment code reviews on an MR (the natural shape of an AI-assisted review), post each concern as a draft note rather than as immediate glab mr note comments. Draft notes stay pending in the user's review until they submit them via the GitLab UI — so the user can edit, drop, or reorder them first.

Conventions:

• Prefix every AI-authored note with **(AI):** so the user can tell which notes came from the agent.
• One concern per note, placed at the most relevant line (not at the top of the file).
• Cross-reference related notes by file:line (e.g. "see the related note on samples.csv:17") rather than duplicating content.
• Never publish the review automatically. Leave the notes pending and tell the user they can edit and submit from the GitLab UI.

Critical gotcha: glab api -f "position[base_sha]=..." does not properly nest position[...] form keys — the draft posts with position: null. You must send the body as JSON via stdin. See references/glab-advanced.md ("Draft Notes / Pending Reviews") for the full recipe.

CI/CD Pipelines

glab ci list                                       # recent pipelines
glab ci status                                     # current pipeline status
glab ci view                                       # view current pipeline
glab ci retry                                      # retry failed pipeline

Projects

glab repo view                                     # current repo info
glab repo clone group/project                      # clone a project
glab repo view group/project --web                 # open in browser

Advanced Usage

For label/milestone management, custom API calls, release management, CI triggers, and cross-project search, see references/glab-advanced.md.