gitai-tool 0.4.0
Generate summaries and code reviews for GitLab Merge Requests or GitHub Pull Requests using LLM
License: MIT
Requires Python: >=3.8
Keywords: git, gitlab, github, merge-requests, pull-requests, cli, llm, ai, summaries, code-review

# GitLab Merge Request Summary Generator

This command-line tool generates a "What's New" summary for a GitLab Merge Request. It uses the GitLab API to fetch technical details (like commit messages and code changes) and then leverages the Google Gemini API to translate them into a clear, benefit-oriented summary suitable for non-technical clients.

## Features

-   Fetches Merge Request details, commit history, and code diffs from GitLab.
-   Uses the Gemini API to generate an intelligent, human-readable summary.
-   Formats the output in Markdown with "New Features" and "Bug Fixes" sections.
-   Creates client-friendly language by focusing on benefits, not technical jargon.
-   Includes a debug mode to inspect the exact prompt sent to the AI.

## Prerequisites

Before you begin, ensure you have the following:

-   Python 3.8+
-   A GitLab account with access to the target project.
-   A [GitLab Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with `api` scope.
-   A [Google Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key).

## Installation

### Install with pipx (recommended)

Install from PyPI and get the global command `gitai-tool`:

```bash
pipx install gitai-tool
gitai-tool --help
```

To upgrade later:

```bash
pipx upgrade gitai-tool
```

### Install with pip (alternative)

```bash
pip install gitai-tool
gitai-tool --help
```

### Persisting configuration (TOML)

When required values are missing, the tool will prompt you interactively and then persist them to `~/.gitai-tool/config.toml` automatically. Subsequent runs will load values from the config file. Precedence matches AWS CLI: command-line flags > environment variables > config file. Example `config.toml`:

```toml
GITLAB_URL = "https://gitlab.com"
GITLAB_PRIVATE_TOKEN = "<your_token>"
GITLAB_PROJECT_ID = "<project_id>"
GEMINI_API_KEY = "<gemini_api_key>"
```

## Usage

After installation with `pipx` or `pip`, use the global command `gitai-tool`. The tool provides two main commands: `summarize` and `code-review`.

Common flags available to all commands:

-   `--gitlab-url`, `--gitlab-private-token`, `--gitlab-project-id`, `--gemini-api-key`
-   `--model`: Gemini model identifier. Defaults to `gemini-2.5-flash`.

### Summarize a Merge Request

Generates a "What's New" summary for a GitLab Merge Request, tailored to different audiences.

```bash
gitai-tool summarize <mr_id> [--style <style1> <style2>...] [--model <full-gemini-model>] [--debug]
```

-   `<mr_id>`: The IID (Internal ID) of the Merge Request to analyze (e.g., `42`).
-   `--style`: One or more summary styles. Choices: `clients`, `devops`, `developers`. You can also use `all` to generate all of them. If omitted, it defaults to generating all styles.
-   `--model`: Full Gemini model name to use. Defaults to `gemini-2.5-flash`.
-   `--debug`: Save the full prompt to a debug file for inspection.

#### Examples

```bash
# Generate summaries for all styles (default behavior)
gitai-tool summarize 42

# Generate a client-focused summary
gitai-tool summarize 42 --style clients

# Generate summaries for both developers and devops
gitai-tool summarize 42 --style developers devops
```

This command will:
1.  Fetch data for the specified Merge Request from the configured GitLab project.
2.  Generate a summary for each specified style using Gemini.
3.  Print the summaries to the console.
4.  Save each summary to a file named `release_summary_mr_<iid>.<style>.md` (e.g., `release_summary_mr_42.clients.md`).

### Review a Merge Request's Code

Generates a comprehensive, structured code review from the Merge Request's diffs.

```bash
gitai-tool code-review <mr_id> [--model <full-gemini-model>] [--debug]
```

-   `<mr_id>`: The IID of the Merge Request to review.
-   `--model`: Full Gemini model name to use. Defaults to `gemini-2.5-flash`.
-   `--debug`: Save the full prompt to a debug file.

This command outputs a `code_review_mr_<iid>.md` file containing a detailed review with structured findings on security, correctness, performance, readability, and more, along with an actionable checklist.

### Debug Mode

For both `summarize` and `code-review`, you can use the `--debug` flag to inspect the exact prompt being sent to the Gemini API.

This will create an additional file named `debug_prompt_mr_<iid>.<style>.md` (for summaries) or `debug_code_review_prompt_mr_<iid>.md` (for code reviews).

## Styles

Choose one or more `--style` options for the `summarize` command to match your target audience. If you don't provide a style, summaries for **all** audiences will be generated by default.

-   **clients**: Benefit-oriented, non-technical “What’s New” for customers. Uses friendly tone and focuses on outcomes. Sections: New Features, Bug Fixes.
-   **devops**: Operational brief for DevOps/SRE. Highlights environment variables, database migrations, seeds, infrastructure/IaC, CI/CD, logging/monitoring, security, dependencies, operational tasks/runbook, and breaking changes.
-   **developers**: Technical synopsis for implementers. Sections may include: Features/Enhancements, Bug Fixes, Refactors, API Changes, Configuration (incl. env vars), Database, Dependencies/Tooling, Tests, Known Issues, Deployment Checklist.

## Output Example

The tool will generate a Markdown file with a summary similar to this:

> We've been working hard to improve your experience! This update brings some exciting new capabilities and resolves a few pesky issues. Here’s a look at what’s new.
>
> ### ✨ New Features
>
> -   **Faster & More Secure Logins:** We've completely overhauled our authentication system, making the login process quicker and more secure for your peace of mind.
> -   **New User Profile Page:** You can now view and manage your account details on a redesigned, easy-to-use profile page.
>
> ### 🐛 Bug Fixes
>
> -   Fixed an issue where the application would occasionally crash when uploading a new profile picture.
> -   Resolved a bug that caused incorrect data to be displayed on the dashboard for some users.