Repository Management¶

Day-to-day repository management built around GitLab issue-driven development. The full list of glab commands lives in CLAUDE.md; this page only covers the ones actually used often.

Branch Workflow (git worktree)¶

This project keeps main clean by isolating work in a separate git worktree per branch.

# Create a work branch
git worktree add ../worktrees/<branch-name> -b <branch-name>
cd ../worktrees/<branch-name>

# Set up dependencies
uv sync --all-groups

# ... implement ...

task test:ci   # unit tests → format check → pre-commit

git add <files>
git commit -m "..."
git push -u origin <branch-name>

Always clean up after the MR is merged:

cd /Users/shotakaha/repos/gitlab.com/qumasan/fnb
git pull
git worktree remove ../worktrees/<branch-name>
git branch -d <branch-name>

Issue Management¶

# List / search
glab issue list
glab issue list --label "Priority::High"

# Create (reuse existing labels — check with glab label list)
glab issue create --label "Type::Bug,Priority::Medium,Effort::03" \
  --title "..." --description "..."

# Change state
glab issue close <id>

Labels follow the Type::* / Priority::* / Effort::* / Status::* scheme. Check glab label list before inventing a new one.

MR Management¶

# Create
glab mr create --source-branch <branch> --target-branch main \
  --title "..." --description "Closes #<issue>"

# Check CI status (always do this before merging)
glab ci status --branch <branch>

# Validate YAML syntax only
glab ci lint .gitlab-ci.yml

Reference the corresponding issue number in the MR description as Closes #NN so it auto-closes on merge.

CI Pipeline Monitoring¶

To check total pipeline duration or per-job timings:

# Latest pipeline status for a branch
glab ci status --branch <branch>

# Pipeline/job details (duration, etc.)
glab api "projects/qumasan%2Ffnb/pipelines/<id>/jobs"
glab api "projects/qumasan%2Ffnb/pipelines/<id>"

See .gitlab-ci.yml for the pipeline structure. test / code-quality / docs-quality / build-package run in parallel via needs: [] (optimized from ~183s to ~43s in 2026-07). docs-quality only runs on MRs that touch docs-related files (rules: changes), so it's normal for it not to appear on code-only MRs.

Reviewing Renovate MRs¶

Renovate creates MRs on renovate/-prefixed branches, where renovate-test (which also validates the build/install) runs instead of test.

glab mr list --search "renovate"

See renovate.json for auto-merge rules on patch updates. Major updates always require manual review.

Routine Maintenance¶

task deps:check      # check for outdated packages
task deps:update      # uv lock --upgrade + sync
task deps:security    # vulnerability scan with pip-audit