# GitLab Gemini Reviewer
An automated code review assistant powered by Google's Gemini AI. This tool analyzes GitLab Merge Requests, provides feedback as comments, creates Jira tickets, and generates QA test plans, streamlining your development workflow.
## ✨ Features
- **Automated Code Analysis**: Leverages the Gemini API to perform detailed code reviews.
- **Smart MR Discussions**:
- Tracks existing discussions to avoid duplicates
- Automatically resolves discussions when issues are fixed
- Filters discussions by severity before creating new ones
- **Inline MR Commenting**: Posts suggestions and issues as discussions directly on the relevant code lines in the merge request.
- **Overall Summary**: Adds a general summary comment to the MR with a quality score.
- **Automatic Approval & Merge**: Can automatically approve and optionally merge requests that meet a configurable quality threshold.
- Control merging behavior with the `--auto-merge` flag or `AUTO_MERGE` environment variable
- **Seamless Jira Integration**:
- Creates a specific sub-task for the code review under the main story.
- Generates and posts a detailed QA test plan as a comment on the parent ticket.
- **Multi-language Support**: Can provide feedback in English or Brazilian Portuguese.
- **Highly Configurable**: All parameters are controlled via environment variables, making it perfect for CI/CD environments.
## 🚀 How It Works
1. **Trigger**: The tool is designed to be run in a CI/CD pipeline when a merge request is created or updated.
2. **Fetch Diffs**: It fetches the code changes (diffs) from the specified GitLab merge request.
3. **Check Existing Discussions**:
- Fetches all existing discussions to avoid duplicates
- Resolves discussions for issues that have been fixed
4. **Analyze**: It sends the code, along with contextual information from the MR title and description, to the Gemini API for analysis.
5. **Post Feedback**: It parses the AI's response and posts feedback to GitLab:
- A general summary note.
- Discussions attached to specific lines of code for each new issue found.
6. **Integrate with Jira**:
- Extracts the Jira ticket key from the MR title (e.g., `PROJ-123`).
- Creates a "Code Review" sub-task.
- Generates a complete QA test plan and posts it as a comment on the main Jira ticket.
## 📦 Installation
You can install the package directly from the source code.
```bash
# Clone the repository first
git clone https://github.com/alairjt/gitlab-gemini-reviewer.git
cd gitlab-gemini-reviewer
# Install using pip
pip install .
```
## ⚙️ Configuration
The tool is configured entirely through environment variables.
| Variable | Description | Default | Required |
| ------------------------ | ------------------------------------------------------------------------ | ------------------------ | :------: |
| `GITLAB_TOKEN` | Your GitLab personal access token with `api` scope. | - | Yes |
| `GEMINI_API_KEY` | Your Google AI Studio API key for Gemini. | - | Yes |
| `CI_PROJECT_ID` | The ID of your GitLab project. Provided by GitLab CI. | - | Yes |
| `CI_MERGE_REQUEST_IID` | The IID (internal ID) of the merge request. Provided by GitLab CI. | - | Yes |
| `CI_SERVER_URL` | The base URL of your GitLab instance (e.g., `https://gitlab.com`). | - | Yes |
| `JIRA_URL` | The base URL of your Jira instance. | - | No |
| `JIRA_USER` | The email or username for the Jira service account. | - | No |
| `JIRA_TOKEN` | The API token for the Jira service account. | - | No |
| `REVIEW_LANGUAGE` | The language for the AI's response (`en` or `pt-BR`). | `pt-BR` | No |
| `GEMINI_MODEL` | The Gemini model to use for the review. | `gemini-1.5-flash` | No |
| `DEBUG` | Set to `1` or `true` for verbose error logging. | - | No |
**Note**: The Jira variables are only required if you want to enable Jira integration.
## ▶️ Usage
After installation, the tool can be run from the command line.
```bash
gemini-reviewer
```
If you encounter a `command not found` error, it means the installation directory is not in your shell's `PATH`. You can either add it or run the tool as a module:
```bash
python -m gitlab_gemini_reviewer.gemini_mr_review
```
### GitLab CI/CD Example
It's intended to be used as a step in your CI/CD pipeline.
```yaml
# .gitlab-ci.yml
gitlab_gemini_reviewer:
stage: review
image: python:3.11-slim
before_script:
- pip install --upgrade pip
- pip install gitlab-gemini-reviewer>=0.3.0
script:
- gemini-reviewer
needs: ['unit test'] # ✅ Ensures that the 'unit test' stage runs before.
rules:
# Main rule:
# 1. Run only on Merge Request events.
# 2. Do NOT run if the target branch is 'production' or 'pre-production'.
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != "production" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != "pre-production"'
when: on_success # Runs if the job in 'needs' succeeds (default).
interruptible: true # ✅ Cancels the old job if a new commit is pushed to the MR, saving resources.
```
## 🔄 Discussion Management
The tool now includes intelligent discussion management features:
### Avoiding Duplicate Discussions
- Automatically checks for existing discussions on the same lines of code
- Prevents creating duplicate discussions for the same issue
- Uses file path and line number to identify duplicate issues
### Automatic Resolution
- Tracks when issues are fixed in subsequent commits
- Automatically resolves discussions when the corresponding issues are no longer present
- Only creates new discussions for issues that don't already have open discussions
### Severity Filtering
- Filters issues by severity before creating discussions
- Helps focus on the most important feedback first
- Configurable through the API response
## ⚙️ Auto-Merge Configuration
You can enable automatic merging of approved MRs using either the command line flag or environment variable:
```bash
# Using command line flag
gemini-reviewer --auto-merge
# Using environment variable
export AUTO_MERGE=true
gemini-reviewer
```
### Important Notes:
- The merge will only be attempted if the review is approved
- The user running the tool must have merge permissions on the target repository
- If the merge fails (e.g., due to merge conflicts), a warning will be logged
## 📄 License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "gitlab-gemini-reviewer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gitlab, gemini, merge request, code review",
"author": null,
"author_email": "Alair Junior <alairjt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/26/1d/993fb2197b7f9b9e8358179ff8efeb55a81b9496aa72d566d89e2360e542/gitlab_gemini_reviewer-0.3.0.tar.gz",
"platform": null,
"description": "# GitLab Gemini Reviewer\n\nAn automated code review assistant powered by Google's Gemini AI. This tool analyzes GitLab Merge Requests, provides feedback as comments, creates Jira tickets, and generates QA test plans, streamlining your development workflow.\n\n## \u2728 Features\n\n- **Automated Code Analysis**: Leverages the Gemini API to perform detailed code reviews.\n- **Smart MR Discussions**: \n - Tracks existing discussions to avoid duplicates\n - Automatically resolves discussions when issues are fixed\n - Filters discussions by severity before creating new ones\n- **Inline MR Commenting**: Posts suggestions and issues as discussions directly on the relevant code lines in the merge request.\n- **Overall Summary**: Adds a general summary comment to the MR with a quality score.\n- **Automatic Approval & Merge**: Can automatically approve and optionally merge requests that meet a configurable quality threshold.\n - Control merging behavior with the `--auto-merge` flag or `AUTO_MERGE` environment variable\n- **Seamless Jira Integration**:\n - Creates a specific sub-task for the code review under the main story.\n - Generates and posts a detailed QA test plan as a comment on the parent ticket.\n- **Multi-language Support**: Can provide feedback in English or Brazilian Portuguese.\n- **Highly Configurable**: All parameters are controlled via environment variables, making it perfect for CI/CD environments.\n\n## \ud83d\ude80 How It Works\n\n1. **Trigger**: The tool is designed to be run in a CI/CD pipeline when a merge request is created or updated.\n2. **Fetch Diffs**: It fetches the code changes (diffs) from the specified GitLab merge request.\n3. **Check Existing Discussions**: \n - Fetches all existing discussions to avoid duplicates\n - Resolves discussions for issues that have been fixed\n4. **Analyze**: It sends the code, along with contextual information from the MR title and description, to the Gemini API for analysis.\n5. **Post Feedback**: It parses the AI's response and posts feedback to GitLab:\n - A general summary note.\n - Discussions attached to specific lines of code for each new issue found.\n6. **Integrate with Jira**:\n - Extracts the Jira ticket key from the MR title (e.g., `PROJ-123`).\n - Creates a \"Code Review\" sub-task.\n - Generates a complete QA test plan and posts it as a comment on the main Jira ticket.\n\n## \ud83d\udce6 Installation\n\nYou can install the package directly from the source code.\n\n```bash\n# Clone the repository first\ngit clone https://github.com/alairjt/gitlab-gemini-reviewer.git\ncd gitlab-gemini-reviewer\n\n# Install using pip\npip install .\n```\n\n## \u2699\ufe0f Configuration\n\nThe tool is configured entirely through environment variables.\n\n| Variable | Description | Default | Required |\n| ------------------------ | ------------------------------------------------------------------------ | ------------------------ | :------: |\n| `GITLAB_TOKEN` | Your GitLab personal access token with `api` scope. | - | Yes |\n| `GEMINI_API_KEY` | Your Google AI Studio API key for Gemini. | - | Yes |\n| `CI_PROJECT_ID` | The ID of your GitLab project. Provided by GitLab CI. | - | Yes |\n| `CI_MERGE_REQUEST_IID` | The IID (internal ID) of the merge request. Provided by GitLab CI. | - | Yes |\n| `CI_SERVER_URL` | The base URL of your GitLab instance (e.g., `https://gitlab.com`). | - | Yes |\n| `JIRA_URL` | The base URL of your Jira instance. | - | No |\n| `JIRA_USER` | The email or username for the Jira service account. | - | No |\n| `JIRA_TOKEN` | The API token for the Jira service account. | - | No |\n| `REVIEW_LANGUAGE` | The language for the AI's response (`en` or `pt-BR`). | `pt-BR` | No |\n| `GEMINI_MODEL` | The Gemini model to use for the review. | `gemini-1.5-flash` | No |\n| `DEBUG` | Set to `1` or `true` for verbose error logging. | - | No |\n\n**Note**: The Jira variables are only required if you want to enable Jira integration.\n\n## \u25b6\ufe0f Usage\n\nAfter installation, the tool can be run from the command line.\n\n```bash\ngemini-reviewer\n```\n\nIf you encounter a `command not found` error, it means the installation directory is not in your shell's `PATH`. You can either add it or run the tool as a module:\n\n```bash\npython -m gitlab_gemini_reviewer.gemini_mr_review\n```\n\n### GitLab CI/CD Example\n\nIt's intended to be used as a step in your CI/CD pipeline.\n\n```yaml\n# .gitlab-ci.yml\n\ngitlab_gemini_reviewer:\n stage: review\n image: python:3.11-slim\n before_script:\n - pip install --upgrade pip\n - pip install gitlab-gemini-reviewer>=0.3.0\n script:\n - gemini-reviewer\n needs: ['unit test'] # \u2705 Ensures that the 'unit test' stage runs before.\n rules:\n # Main rule:\n # 1. Run only on Merge Request events.\n # 2. Do NOT run if the target branch is 'production' or 'pre-production'.\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != \"production\" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != \"pre-production\"'\n when: on_success # Runs if the job in 'needs' succeeds (default).\n interruptible: true # \u2705 Cancels the old job if a new commit is pushed to the MR, saving resources.\n\n\n```\n\n## \ud83d\udd04 Discussion Management\n\nThe tool now includes intelligent discussion management features:\n\n### Avoiding Duplicate Discussions\n- Automatically checks for existing discussions on the same lines of code\n- Prevents creating duplicate discussions for the same issue\n- Uses file path and line number to identify duplicate issues\n\n### Automatic Resolution\n- Tracks when issues are fixed in subsequent commits\n- Automatically resolves discussions when the corresponding issues are no longer present\n- Only creates new discussions for issues that don't already have open discussions\n\n### Severity Filtering\n- Filters issues by severity before creating discussions\n- Helps focus on the most important feedback first\n- Configurable through the API response\n\n## \u2699\ufe0f Auto-Merge Configuration\n\nYou can enable automatic merging of approved MRs using either the command line flag or environment variable:\n\n```bash\n# Using command line flag\ngemini-reviewer --auto-merge\n\n# Using environment variable\nexport AUTO_MERGE=true\ngemini-reviewer\n```\n\n### Important Notes:\n- The merge will only be attempted if the review is approved\n- The user running the tool must have merge permissions on the target repository\n- If the merge fails (e.g., due to merge conflicts), a warning will be logged\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Gemini-based tool to review GitLab Merge Requests.",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/alairjt/gitlab-gemini-reviewer/issues",
"Homepage": "https://github.com/alairjt/gitlab-gemini-reviewer"
},
"split_keywords": [
"gitlab",
" gemini",
" merge request",
" code review"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0b3723fc9255fd6c5c30df94f40049fd72b78a11328a4f177e4ceccf83c17caf",
"md5": "85020fba00691428720703efbb01a9ad",
"sha256": "1b1d720aea1a2ccd417ee05d6ba6cbf8cd0ebbe1902b6161f2eeeefd42318dbf"
},
"downloads": -1,
"filename": "gitlab_gemini_reviewer-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85020fba00691428720703efbb01a9ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16743,
"upload_time": "2025-07-24T17:12:28",
"upload_time_iso_8601": "2025-07-24T17:12:28.071507Z",
"url": "https://files.pythonhosted.org/packages/0b/37/23fc9255fd6c5c30df94f40049fd72b78a11328a4f177e4ceccf83c17caf/gitlab_gemini_reviewer-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "261d993fb2197b7f9b9e8358179ff8efeb55a81b9496aa72d566d89e2360e542",
"md5": "ca252874e77ef62248f84b392279ccb5",
"sha256": "8dbb68827fb3bef5fb958f4c3f56be3637963f1bb431591c490af7481a06b2d3"
},
"downloads": -1,
"filename": "gitlab_gemini_reviewer-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "ca252874e77ef62248f84b392279ccb5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18819,
"upload_time": "2025-07-24T17:12:29",
"upload_time_iso_8601": "2025-07-24T17:12:29.273153Z",
"url": "https://files.pythonhosted.org/packages/26/1d/993fb2197b7f9b9e8358179ff8efeb55a81b9496aa72d566d89e2360e542/gitlab_gemini_reviewer-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 17:12:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alairjt",
"github_project": "gitlab-gemini-reviewer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gitlab-gemini-reviewer"
}
JSON
