docs: Update documentation for CP2 merge request support
Updates project documentation to reflect the complete CP2 feature set with merge request ingestion and robot mode capabilities. README.md: - Add MR-related CLI examples (gi list mrs, gi show mr, gi ingest) - Document robot mode (--robot flag, GI_ROBOT env, auto-detect) - Update feature list with MR support and DiffNote positions - Add configuration section with all config file options - Expand CLI reference with new commands and flags AGENTS.md: - Add MR ingestion patterns for AI agent consumption - Document robot mode JSON schemas for parsing - Include error handling patterns with exit codes - Add discussion/note querying examples for code review context Cargo.toml: - Bump version to 0.2.0 reflecting major feature addition The documentation emphasizes the robot mode design which enables AI agents like Claude Code to reliably parse gi output for automated GitLab workflow integration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
85
README.md
85
README.md
@@ -1,15 +1,16 @@
|
||||
# gi - GitLab Inbox
|
||||
|
||||
A command-line tool for managing GitLab issues locally. Syncs issues, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying and filtering.
|
||||
A command-line tool for managing GitLab issues and merge requests locally. Syncs issues, MRs, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying and filtering.
|
||||
|
||||
## Features
|
||||
|
||||
- **Local-first**: All data stored in SQLite for instant queries
|
||||
- **Incremental sync**: Cursor-based sync only fetches changes since last sync
|
||||
- **Full re-sync**: Reset cursors and fetch all data from scratch when needed
|
||||
- **Multi-project**: Track issues across multiple GitLab projects
|
||||
- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date
|
||||
- **Multi-project**: Track issues and MRs across multiple GitLab projects
|
||||
- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches
|
||||
- **Raw payload storage**: Preserves original GitLab API responses for debugging
|
||||
- **Discussion threading**: Full support for issue and MR discussions including inline code review comments
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -36,11 +37,20 @@ gi auth-test
|
||||
# Sync issues from GitLab
|
||||
gi ingest --type issues
|
||||
|
||||
# Sync merge requests from GitLab
|
||||
gi ingest --type mrs
|
||||
|
||||
# List recent issues
|
||||
gi list issues --limit 10
|
||||
|
||||
# List open merge requests
|
||||
gi list mrs --state opened
|
||||
|
||||
# Show issue details
|
||||
gi show issue 123 --project group/repo
|
||||
|
||||
# Show MR details with discussions
|
||||
gi show mr 456 --project group/repo
|
||||
```
|
||||
|
||||
## Configuration
|
||||
@@ -163,13 +173,19 @@ Checks performed:
|
||||
Sync data from GitLab to local database.
|
||||
|
||||
```bash
|
||||
# Issues
|
||||
gi ingest --type issues # Sync all projects
|
||||
gi ingest --type issues --project group/repo # Single project
|
||||
gi ingest --type issues --force # Override stale lock
|
||||
gi ingest --type issues --full # Full re-sync (reset cursors)
|
||||
|
||||
# Merge Requests
|
||||
gi ingest --type mrs # Sync all projects
|
||||
gi ingest --type mrs --project group/repo # Single project
|
||||
gi ingest --type mrs --full # Full re-sync (reset cursors)
|
||||
```
|
||||
|
||||
The `--full` flag resets sync cursors and fetches all data from scratch, useful when:
|
||||
The `--full` flag resets sync cursors and discussion watermarks, then fetches all data from scratch. Useful when:
|
||||
- Assignee data or other fields were missing from earlier syncs
|
||||
- You want to ensure complete data after schema changes
|
||||
- Troubleshooting sync issues
|
||||
@@ -201,6 +217,35 @@ gi list issues --json # JSON output
|
||||
|
||||
Output includes: IID, title, state, author, assignee, labels, and update time.
|
||||
|
||||
### `gi list mrs`
|
||||
|
||||
Query merge requests from local database.
|
||||
|
||||
```bash
|
||||
gi list mrs # Recent MRs (default 50)
|
||||
gi list mrs --limit 100 # More results
|
||||
gi list mrs --state opened # Only open MRs
|
||||
gi list mrs --state merged # Only merged MRs
|
||||
gi list mrs --state closed # Only closed MRs
|
||||
gi list mrs --state locked # Only locked MRs
|
||||
gi list mrs --state all # All states
|
||||
gi list mrs --author username # By author (@ prefix optional)
|
||||
gi list mrs --assignee username # By assignee (@ prefix optional)
|
||||
gi list mrs --reviewer username # By reviewer (@ prefix optional)
|
||||
gi list mrs --draft # Only draft/WIP MRs
|
||||
gi list mrs --no-draft # Exclude draft MRs
|
||||
gi list mrs --target-branch main # By target branch
|
||||
gi list mrs --source-branch feature/foo # By source branch
|
||||
gi list mrs --label needs-review # By label (AND logic)
|
||||
gi list mrs --since 7d # Updated in last 7 days
|
||||
gi list mrs --project group/repo # Filter by project
|
||||
gi list mrs --sort created --order asc # Sort options
|
||||
gi list mrs --open # Open first result in browser
|
||||
gi list mrs --json # JSON output
|
||||
```
|
||||
|
||||
Output includes: IID, title (with [DRAFT] prefix if applicable), state, author, assignee, labels, and update time.
|
||||
|
||||
### `gi show issue`
|
||||
|
||||
Display detailed issue information.
|
||||
@@ -212,14 +257,27 @@ gi show issue 123 --project group/repo # Disambiguate if needed
|
||||
|
||||
Shows: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions.
|
||||
|
||||
### `gi show mr`
|
||||
|
||||
Display detailed merge request information.
|
||||
|
||||
```bash
|
||||
gi show mr 456 # Show MR !456
|
||||
gi show mr 456 --project group/repo # Disambiguate if needed
|
||||
```
|
||||
|
||||
Shows: title, description, state, draft status, author, assignees, reviewers, labels, source/target branches, merge status, web URL, and threaded discussions. Inline code review comments (DiffNotes) display file context in the format `[src/file.ts:45]`.
|
||||
|
||||
### `gi count`
|
||||
|
||||
Count entities in local database.
|
||||
|
||||
```bash
|
||||
gi count issues # Total issues
|
||||
gi count mrs # Total MRs (with state breakdown)
|
||||
gi count discussions # Total discussions
|
||||
gi count discussions --type issue # Issue discussions only
|
||||
gi count discussions --type mr # MR discussions only
|
||||
gi count notes # Total notes (shows system vs user breakdown)
|
||||
```
|
||||
|
||||
@@ -233,7 +291,7 @@ gi sync-status
|
||||
|
||||
Displays:
|
||||
- Last sync run details (status, timing)
|
||||
- Cursor positions per project and resource type
|
||||
- Cursor positions per project and resource type (issues and MRs)
|
||||
- Data summary counts
|
||||
|
||||
### `gi migrate`
|
||||
@@ -282,12 +340,16 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables:
|
||||
|-------|---------|
|
||||
| `projects` | Tracked GitLab projects with metadata |
|
||||
| `issues` | Issue metadata (title, state, author, due date, milestone) |
|
||||
| `merge_requests` | MR metadata (title, state, draft, branches, merge status) |
|
||||
| `milestones` | Project milestones with state and due dates |
|
||||
| `labels` | Project labels with colors |
|
||||
| `issue_labels` | Many-to-many issue-label relationships |
|
||||
| `issue_assignees` | Many-to-many issue-assignee relationships |
|
||||
| `mr_labels` | Many-to-many MR-label relationships |
|
||||
| `mr_assignees` | Many-to-many MR-assignee relationships |
|
||||
| `mr_reviewers` | Many-to-many MR-reviewer relationships |
|
||||
| `discussions` | Issue/MR discussion threads |
|
||||
| `notes` | Individual notes within discussions (with system note flag) |
|
||||
| `notes` | Individual notes within discussions (with system note flag and DiffNote position data) |
|
||||
| `sync_runs` | Audit trail of sync operations |
|
||||
| `sync_cursors` | Cursor positions for incremental sync |
|
||||
| `app_locks` | Crash-safe single-flight lock |
|
||||
@@ -334,15 +396,16 @@ cargo clippy
|
||||
|
||||
## Current Status
|
||||
|
||||
This is Checkpoint 1 (CP1) of the GitLab Knowledge Engine project. Currently implemented:
|
||||
This is Checkpoint 2 (CP2) of the GitLab Knowledge Engine project. Currently implemented:
|
||||
|
||||
- Issue ingestion with cursor-based incremental sync
|
||||
- Discussion and note syncing for issues
|
||||
- Rich filtering and querying
|
||||
- Full re-sync capability
|
||||
- Merge request ingestion with cursor-based incremental sync
|
||||
- Discussion and note syncing for issues and MRs
|
||||
- DiffNote support for inline code review comments
|
||||
- Rich filtering and querying for both issues and MRs
|
||||
- Full re-sync capability with watermark reset
|
||||
|
||||
Not yet implemented:
|
||||
- Merge request support (CP2)
|
||||
- Semantic search with embeddings (CP3+)
|
||||
- Backup and reset commands
|
||||
|
||||
|
||||
Reference in New Issue
Block a user