glreview 0.3.0

GitLab code review tracking for scientific software

glreview

GitLab code review tracking for scientific software.

Features

• Track review status of source modules with git commit precision
• GitLab integration - creates issues, verifies completion, closes on cancel
• AI-assisted review - Claude Code integration for automated analysis
• Change detection - warns if code changes during review
• Module analysis - shows classes/functions in review issues
• Customizable templates - Jinja2-based issue templates
• CI-friendly - exit codes for automated checks
• Priority rules - pattern-based priority assignment

Installation

pip install glreview

Quick Start

1. Configure source patterns

Add to pyproject.toml:

[tool.glreview]
sources = ["src/**/*.py"]
exclude = ["**/_version.py", "**/test_*.py"]

Adjust the patterns to match your project structure.

2. Set up GitLab authentication

export GITLAB_PRIVATE_TOKEN=glpat-xxxxxxxxxxxx

# For self-hosted GitLab
export GITLAB_URL=https://gitlab.example.com

3. Initialize the registry

glreview init

This creates the .glreview/ directory with registry.json. Commit it to version control.

4. Check what needs review

glreview status

5. Review a module

# Start a review (creates GitLab issue)
glreview start src/mymodule/core.py --assignee @reviewer

# Reviewer examines the code and closes the GitLab issue when done

# Sign off on the completed review
glreview signoff src/mymodule/core.py

# Commit the updated registry
git add .glreview/
git commit -m "signoff: src/mymodule/core.py"

Review Workflow

1. glreview start PATH        →  Creates GitLab issue, status: in_progress
2. Reviewer examines code     →  Reviews code, adds comments to issue
3. Reviewer closes issue      →  Signals review is complete
4. glreview signoff PATH      →  Records review, status: reviewed
5. Code changes later...      →  Status shown as "changed since review"
6. glreview start PATH        →  Re-review cycle begins

Lifecycle diagram

  ┌─────────────┐
  │ needs_review│◄──────────────────┐
  └──────┬──────┘                   │
         │ start                    │ cancel
         ▼                          │
  ┌─────────────┐                   │
  │ in_progress │───────────────────┤
  └──────┬──────┘                   │
         │ signoff                  │
         ▼                          │
  ┌─────────────┐   code changes    │
  │  reviewed   │───────────────────┘
  └─────────────┘   (re-review)

Handling changes during review

If code changes while a review is in progress:

# See what changed since review started
glreview diff src/module.py --since-start

# Option 1: Acknowledge and sign off anyway
glreview signoff src/module.py --acknowledge

# Option 2: Restart the review from current commit
glreview cancel src/module.py --restart

Viewing diffs

# See changes since last review (for deciding whether to re-review)
glreview diff src/module.py

# See changes during current review (before signing off)
glreview diff src/module.py --since-start

# Open diff in GitLab web UI
glreview diff src/module.py --web

AI-Assisted Review

glreview integrates with Claude Code for automated code analysis.

Setup: Generate project context

Before running reviews, let Claude analyze your project structure:

# Generate project context (one-time setup)
glreview claude-init

# Update after significant changes
glreview claude-sync

This creates .glreview/context.json (commit to version control). Claude uses this to:

• Include relevant test files in reviews
• Check against project conventions
• Understand how modules fit together

You can view the generated context with glreview claude-context [PATH].

Running a review

# Run review (requires claude CLI)
glreview claude-review src/module.py

# Post findings to GitLab issue
glreview claude-review src/module.py --post

# Preview prompt without running
glreview claude-review src/module.py --dry-run

Reviews evaluate: organization, readability, purpose, error handling, test coverage, corner cases, documentation, integration, performance, and security.

Each criterion is rated:

• OK - No issues found
• SUGGESTED - Optional improvements
• REQUIRED - Must fix before sign-off

Fixing issues

# Fix REQUIRED issues (interactive session)
glreview claude-fix src/module.py

# Fix all issues (REQUIRED + SUGGESTED)
glreview claude-fix src/module.py --all

# Non-interactive mode (for scripts)
glreview claude-fix src/module.py --batch

By default, claude-fix runs interactively so you can guide Claude as it makes changes.

GitLab labels

glreview uses scoped labels to track review status:

Label	Meaning
review::pending	Review started, awaiting analysis
review::ok	Claude review passed, ready to sign off
review::required	Has issues that must be fixed
priority::critical/high/medium/low	Module priority level

Labels are updated automatically when you run claude-review --post.

Commands

Command	Description
glreview init	Initialize (idempotent - safe to re-run)
glreview status	Show review progress and module status
glreview start PATH	Start a review (creates GitLab issue)
glreview signoff PATH	Sign off on a completed review
glreview cancel PATH	Cancel or restart a review
glreview diff PATH	Show changes since last review
glreview claude-review PATH	Run AI-assisted review with Claude
glreview claude-fix PATH	Fix issues identified in review
glreview claude-init	Generate AI project context
glreview claude-sync	Update AI context for changed files
glreview claude-context [PATH]	View AI-generated context
glreview report	Generate coverage report (markdown/json/badge)
glreview list	List all modules
glreview reviewers	List available reviewers
glreview check	CI check for changes
glreview sync	Sync registry with filesystem
glreview ci-config	Print recommended GitLab CI configuration

Configuration

Add to pyproject.toml:

[tool.glreview]
sources = ["src/**/*.py"]
exclude = ["**/_version.py", "**/test_*.py"]

# Custom issue template (optional)
issue_template = ".glreview/issue_template.md"

# Priority rules (first match wins)
[[tool.glreview.priority]]
pattern = "src/**/core.py"
level = "critical"
reviewers_required = 2

[[tool.glreview.priority]]
pattern = "src/**/*.py"
level = "medium"
reviewers_required = 1

CI Integration

glreview can automatically sync and report on every push.

Setup

1. Create a Project Access Token with write_repository scope:

   • Settings → Access Tokens → Add new token
   • Role: Maintainer, Scopes: write_repository

2. Add it as a CI variable:

   • Settings → CI/CD → Variables
   • Key: PUSH_TOKEN, Value: the token, Masked: yes

3. Add CI configuration:

   glreview ci-config
   

Example configuration

review-sync:
  variables:
    GIT_TERMINAL_PROMPT: "0"
  script:
    - pip install glreview
    - git config user.email "gitlab-ci@$CI_SERVER_HOST"
    - git config user.name "GitLab CI"
    - git remote set-url origin "https://oauth2:${PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
    - git checkout $CI_COMMIT_BRANCH
    - glreview report --sync --format markdown --output REVIEW_COVERAGE.md
    - git add REVIEW_COVERAGE.md .glreview/ || true
    - 'git diff --cached --quiet || git commit -m "chore: update review registry"'
    - 'git diff origin/$CI_COMMIT_BRANCH --quiet && echo "No changes to push" || git push origin HEAD:$CI_COMMIT_BRANCH -o ci.skip'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Run glreview ci-config for complete configuration including MR sync and release gates.

License

MIT