Gerrit

1. Overview

Gerrit is a web-based code review system that integrates with Git. It provides a collaborative platform for developers to review, comment on, and approve code changes before they are merged into the main codebase. Gerrit is widely used in open-source projects and enterprise development environments to maintain code quality and facilitate team collaboration.

Through the GoInsight Gerrit node, you can seamlessly integrate Gerrit code review operations into your automation workflows. This node enables you to:

• Query and retrieve change information based on various criteria such as status, owner, and project.
• Access detailed change data including comments, commit messages, and change-level messages.
• Manage and browse Gerrit projects with filtering and pagination support.

2. Prerequisites

Before using this node, please ensure the following requirements are met:

• Gerrit Account: You need a valid Gerrit account with appropriate access permissions to the target Gerrit server.
• API Access: Ensure that your account has the necessary permissions to access the Gerrit REST API.
• Authentication Credentials: Prepare your HTTP credentials (username and HTTP password) or other authentication tokens required by your Gerrit server.

3. Credentials

For detailed instructions on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

The Gerrit node provides operations centered around five main resources: Change, Change Content (comments, messages, commits), Change Files (file lists, diffs, patches), Project, and Review. You can query and retrieve change information, access comments and commit messages, view file changes and diffs, browse projects, and submit code reviews.

Operation Details

Query Changes

Queries Gerrit changes using Gerrit query syntax. Supports filtering by status, owner, project, branch, and more. Returns a paginated list of changes matching the query criteria.

Options:

• Query: Gerrit query syntax string, e.g., status:open, owner:self, project:myproject.
• Limit: Maximum number of results to return, default 25, max 500.
• Offset: Pagination offset, default 0.

Output:

• Changes (object-array): List of change objects.
• Total (number): Number of changes returned in this query.
• MoreChanges (bool): Whether there are more changes available to query.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message if any; empty if successful.

Get Changes

Retrieves detailed information for multiple Gerrit changes in batch. Supports both change numbers and full change IDs.

Input Parameters:

• ChangeIds: List of change IDs to retrieve.

Output:

• Changes (object-array): List of successfully retrieved change details.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved changes.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

Get Change Comments

Retrieves comments for multiple Gerrit changes in batch. Comments are organized by file path.

Input Parameters:

• ChangeIds: List of change IDs to retrieve comments for.

Output:

• Comments (object-array): List of successfully retrieved comments.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved comments.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

List Change Messages

Retrieves change-level messages for multiple Gerrit changes in batch. Change messages include review comments (with +1/-1 votes), patch set upload notifications, and status updates (abandon, restore, etc.).

Input Parameters:

• ChangeIds: List of change IDs to retrieve messages for.

Output:

• Messages (object-array): List of successfully retrieved messages.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved messages.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

Get Commit Messages

Retrieves commit messages for multiple Gerrit changes in batch. Includes commit author, committer, message, and parent information.

Input Parameters:

• ChangeIds: List of change IDs to retrieve commit messages for.

Options:

• RevisionId: Revision ID, defaults to current for the latest revision.

Output:

• CommitMessages (object-array): List of successfully retrieved commit info.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved commit messages.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

Get Change Files

Retrieves the list of modified files for multiple Gerrit changes in batch. Returns file metadata including lines inserted/deleted, file size, and status for each modified file.

Input Parameters:

• ChangeIds: List of change IDs to retrieve files for.

Options:

• RevisionId: Revision ID, default is current.

Output:

• Files (object-array): List of successfully retrieved file lists.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved file lists.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

Get File Diff

Retrieves the detailed code diff for a specific file in a Gerrit change. Returns the diff content including metadata about the file versions, change type, and the actual diff content with context lines.

Input Parameters:

• ChangeId: Change ID to retrieve diff for.
• FilePath: Path of the file to get diff for.

Options:

• RevisionId: Revision ID, default is current.
• Base: Base revision for comparison.
• Context: Number of context lines, default is 3.

Output:

• Diff (object): The diff details containing meta info and content.
• ChangeId (string): The change ID.
• FilePath (string): The file path.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any; empty if successful.

Get Patch

Retrieves the formatted patch content for multiple Gerrit changes in batch. Supports both change numbers and full change IDs. The patch content can be returned as decoded text or base64 encoded format.

Input Parameters:

• ChangeIds: List of change IDs to retrieve patches for.

Options:

• RevisionId: Revision ID, default is current.
• DecodeBase64: If true (default), decodes base64 to readable text.

Output:

• Patches (object-array): List of successfully retrieved patches.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved patches.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

List Projects

Lists Gerrit projects with optional filtering by prefix or name match. Supports pagination and optionally includes project descriptions.

Options:

• Prefix: Project name prefix filter, returns only projects starting with this prefix.
• Match: Project name match filter, returns only projects containing this string.
• Limit: Maximum number of results to return, default 25.
• Offset: Pagination offset, default 0.
• Description: Whether to include project description information, default false.

Output:

• Projects (object-array): List of project objects.
• Total (number): Number of projects returned in this query.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message if any; empty if successful.

Get Projects

Retrieves detailed information for multiple Gerrit projects in batch.

Input Parameters:

• ProjectNames: List of project names to retrieve.

Output:

• Projects (object-array): List of successfully retrieved project details.
• FailedItems (object-array): List of failed retrievals.
• SuccessCount (number): Number of successfully retrieved projects.
• FailedCount (number): Number of failed retrievals.
• StatusCode (number): Operation status code (200 all success, 207 partial success, 500 all failed, -1 parameter error).
• ErrorMessage (string): Error message if any; empty if successful.

Submit Review

Submits a code review on a Gerrit change revision. Allows setting review message, label scores (like Code-Review, Verified), and file-level comments. The reviewer will be automatically added to the change if labels are set.

Input Parameters:

• ChangeId: Change ID to submit review for.

Options:

• RevisionId: Revision ID, default is current.
• Message: Review comment message.
• Labels: Label scores as JSON string, e.g., {"Code-Review": 1}.
• Comments: File-level comments as JSON string.
• Tag: Review tag to identify the source.

Output:

• Result (object): The review result containing labels and reviewers.
• ChangeId (string): The change ID.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any; empty if successful.

5. Example Usage

This section guides you through creating a simple workflow to query open changes from your Gerrit server.

Scenario

You want to create an automated workflow that retrieves all open code review changes assigned to you, allowing you to quickly see what needs your attention.

Workflow Overview

The workflow consists of: Start → Gerrit (Query Changes) → Answer

Step-by-Step Guide

1. Add the Tool Node
   • In the workflow canvas, click the "+" button to add a new node.
   • Select the "Tool" tab in the popup panel.
   • Find and select Gerrit from the tool list.
   • From the list of supported operations, click Query Changes to add the corresponding node to the canvas.
2. Configure the Node
   • Click the newly added Query Changes node to expand its configuration panel on the right side.
   • Credentials Configuration: At the top of the panel, locate the credentials field. Click the dropdown menu and select your pre-configured Gerrit credentials.
   • Parameter Configuration:
   • Query: Enter your Gerrit query string. For example:
   • status:open owner:self - to find all your open changes
   • status:open reviewer:self - to find changes where you are a reviewer
   • project:myproject status:merged - to find merged changes in a specific project
   • Limit: Set the maximum number of results to return. The default is 25, and you can set it up to 500.
   • Offset: If you need pagination, set the offset value. Default is 0.
3. Run and Verify
   • Once all parameters are correctly configured, the error indicator in the top-right corner of the canvas will disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After successful execution, click the log icon in the top-right corner to view the detailed input and output of the node, verifying that the operation was successful.

Final Workflow

After completing the above steps, your workflow is fully configured. Upon clicking "Test Run," the Query Changes node will retrieve a list of Gerrit changes matching your query criteria. The output will include change details such as project name, branch, subject, status, and owner information.

6. FAQs

Q: I'm getting a 401 Unauthorized error. What should I do?

A: This error typically indicates authentication issues. Please check the following:

• Ensure your Gerrit credentials are correctly configured in GoInsight.
• Verify that your HTTP password is correct (this is different from your regular login password in Gerrit).
• Check if your account has API access enabled on the Gerrit server.

Q: I'm getting a 404 Not Found error when retrieving changes or projects.

A: This error usually means the requested resource doesn't exist. Please verify:

• The change ID or project name is correct and exists on your Gerrit server.
• You have permission to access the specified change or project.
• The change hasn't been deleted or abandoned (for change queries).

Q: What is the difference between "Get Changes" and "Query Changes"?

A: These operations serve different purposes:

• Query Changes: Uses Gerrit query syntax to search for changes based on criteria like status, owner, project, etc. It returns a list of matching changes.
• Get Changes: Retrieves detailed information for specific changes when you already know the change IDs.

Q: How do I format the Query parameter for Query Changes?

A: The Query parameter uses Gerrit's standard query syntax. Common examples include:

• status:open - Open changes
• status:merged - Merged changes
• owner:self - Your own changes
• reviewer:self - Changes where you're a reviewer
• project:projectname - Changes in a specific project
• branch:branchname - Changes on a specific branch

You can combine multiple criteria: status:open owner:self project:myproject

Q: Why do some batch operations return a 207 status code?

A: A 207 status code indicates "partial success" - some items in your batch request succeeded while others failed. Check the FailedItems output to see which items failed and why, and the SuccessCount/FailedCount fields for a quick summary.

7. Official Documentation

For more advanced usage and detailed API reference, please visit the official Gerrit documentation:

Gerrit REST API Documentation