---
description: "When working with GitLab or GitHub — issues, merge requests, pull requests, CI pipelines, labels"
globs: ""
alwaysApply: false
---

# VCS Operations Reference (GitLab & GitHub)

Single source of truth for all VCS CLI commands, label taxonomy, issue templates, and project resolution.

## VCS Auto-Detection

Detect which platform the current repo uses:

```bash
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
if echo "$REMOTE_URL" | grep -q "github.com"; then
  VCS=github    # use `gh`
else
  VCS=gitlab    # use `glab`
fi
```

Session Config overrides:
- `vcs: github|gitlab` -- force a specific platform
- `gitlab-host: <host>` -- override auto-detected GitLab host

## Dynamic Project Resolution

Never hardcode project IDs. Resolve at runtime.

### Current Project

```bash
# GitLab — numeric project ID
glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])"

# GitHub — owner/name
gh repo view --json nameWithOwner -q '.nameWithOwner'
```

### Cross-Project Queries

```bash
# GitLab — resolve by name
glab api "projects?search=<project-name>" | python3 -c "import json,sys; [print(p['id'], p['path_with_namespace']) for p in json.load(sys.stdin)]"

# GitHub — resolve repo details
gh api "repos/<owner>/<name>" --jq '.full_name'
```

---

## Common CLI Commands

### GitLab (glab)

```bash
# Issues
glab issue list --per-page 50                              # All open issues
glab issue list --label "status:ready" --per-page 10       # Filtered by label
glab issue list --label "priority:high" --per-page 10      # High priority
glab issue list --closed --per-page 10                     # Recently closed
glab issue view <IID>                                      # View issue details
glab issue view <IID> --comments                           # With comments
glab issue create --title "title" --label "priority:high,status:ready"
glab issue update <IID> --label "status:in-progress"
glab issue close <IID>
glab issue note <IID> -m "Comment text"                    # Add comment

# MRs
glab mr list                                               # Open MRs
glab mr create --fill --draft                              # Create draft MR
glab mr merge <MR_IID>                                     # Merge MR

# Pipelines
glab pipeline list --per-page 5                            # Recent pipelines
glab pipeline status <ID>                                  # Pipeline details

# API (reads host from git remote automatically)
PROJECT_ID=$(glab repo view --output json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
glab api "projects/$PROJECT_ID/issues?state=opened&per_page=50"
glab api "projects/$PROJECT_ID/milestones?state=active"
```

### GitHub (gh)

```bash
# Issues
gh issue list --limit 50                                   # All open issues
gh issue list --label "status:ready" --limit 10            # Filtered by label
gh issue list --label "priority:high" --limit 10           # High priority
gh issue list --state closed --limit 10                    # Recently closed
gh issue view <NUMBER>                                     # View issue details
gh issue view <NUMBER> --comments                          # With comments
gh issue create --title "title" --label "priority:high,status:ready"
gh issue edit <NUMBER> --add-label "status:in-progress"
gh issue close <NUMBER>
gh issue comment <NUMBER> --body "Comment text"            # Add comment

# PRs
gh pr list --state open                                    # Open PRs
gh pr create --fill --draft                                # Create draft PR
gh pr merge <NUMBER>                                       # Merge PR

# Workflows (CI)
gh run list --limit 5                                      # Recent workflow runs
gh run view <RUN_ID>                                       # Run details

# API
gh api "repos/{owner}/{repo}/issues?state=open&per_page=50"
gh api "repos/{owner}/{repo}/milestones?state=open"
```

---

## glab CLI Quirks

These are known differences from `gh` that cause frequent mistakes:

| Quirk | Correct | Wrong |
|-------|---------|-------|
| Listing closed issues | `glab issue list --closed` | `glab issue list --state closed` |
| Confirmations | glab has NO `--yes` flag | Do not pass `--yes` |
| Comprehensive listing | `glab issue list --per-page 100` | Default per-page is small |
| Pagination flag | `--per-page N` (glab) | `--limit N` (that is gh syntax) |

---

## Label Taxonomy

### Priority Labels
- `priority:critical` -- blocking production or users
- `priority:high` -- important, schedule this sprint
- `priority:medium` -- plan for next sprint
- `priority:low` -- backlog, nice-to-have

### Status Labels
- `status:ready` -- defined, ready to pick up
- `status:in-progress` -- actively being worked on
- `status:review` -- MR/PR created, awaiting review
- `status:blocked` -- waiting on external dependency

### Area Labels
- `area:frontend` | `area:backend` | `area:database`
- `area:ai` | `area:security` | `area:testing`
- `area:ci` | `area:infrastructure` | `area:compliance`
- `area:skills` | `area:vcs` | `area:harness`

### Type Labels
- `bug` | `feature` | `enhancement` | `refactor`
- `chore` | `documentation` | `epic` | `discovery`

---

## Issue Templates

### Bug

```markdown
## Description
What happens vs. what should happen.

## Steps to Reproduce
1.
2.

## Root Cause (if known)

## Acceptance Criteria
- [ ]
```

### Feature

```markdown
## Goal
What should be achieved and why.

## Tasks
- [ ]

## Acceptance Criteria
- [ ]

## Session Type
[housekeeping|feature|deep]
```

### Carryover (from /close)

```markdown
## [Carryover] Original Task Description

### What was completed
- [completed items]

### What remains
- [ ] [remaining task 1]
- [ ] [remaining task 2]

### Context for next session
[relevant context, file paths, decisions made]

### Original Issue
Relates to #ORIGINAL_IID
```

### Discovery Finding

```markdown
## [Discovery] <finding title>

**Probe:** <probe_name>
**Severity:** <priority:critical|high|medium|low>
**Category:** <code|infra|ui|arch|session|audit|vault|feature>

### Finding
<description of the problem>

### Evidence
- **File:** `<file_path>`
- **Line:** <line_number>
- **Code:**
  ```
  <matched_text with surrounding context>
  ```

### Impact
<why this matters>

### Recommended Fix
<concrete fix suggestion>

### Acceptance Criteria
- [ ] <specific, verifiable condition>
- [ ] Quality gates pass after fix
```

Labels for discovery findings: `type:discovery`, `priority:<level>`, `area:<inferred>`, `status:ready`



---

CI pipeline commands are listed in the Common CLI Commands section above (Pipelines/Workflows). Interpret: green=passed, red=failed (investigate before proceeding), pending=in progress.