glreview 0.2.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
• AI-generated context - Claude analyzes your project to enhance reviews
• 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

GitLab Authentication

For GitLab integration, set an environment variable:

export GITLAB_PRIVATE_TOKEN=glpat-xxxxxxxxxxxx

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

In CI pipelines, CI_JOB_TOKEN is used automatically.

Quick Start

# Initialize in your project
glreview init

# Check status
glreview status

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

# After review is complete (issue closed)
glreview signoff src/mymodule/core.py

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 claude-review PATH	Run AI-assisted review with Claude
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

Review Lifecycle

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

Key behaviors:

• signoff warns if file changed during review (use --acknowledge to proceed)
• cancel closes the GitLab issue by default (use --leave-open to skip)
• cancel --restart keeps the issue open and updates the start commit

AI-Assisted Review

Use Claude Code for automated code analysis:

# 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.

Large files are automatically chunked.

AI-Generated Project Context

For better reviews, let Claude analyze your project structure:

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

# View the generated context
glreview claude-context                    # Project overview
glreview claude-context src/module.py      # Module-specific context

# Update after significant changes
glreview claude-sync

This creates .glreview/context.json which should be committed to version control. Claude analyzes your codebase to identify:

• Project conventions - coding patterns, architecture, style
• Test associations - which test files cover which modules (regardless of naming conventions)
• Import relationships - what depends on what
• Module purposes - what each module does

When you run claude-review, this context is automatically included, giving Claude:

• The actual test file content for the module being reviewed
• Project conventions to check against
• Understanding of how the module fits in the larger codebase

The context file is human-editable - you can refine Claude's analysis or add notes.

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 review_registry.json || 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