Overview

The summary(same with describe) tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels.

The tool can be triggered automatically every time a new PR be created, or it can be invoked manually by commenting on any PR:

/describe

Example usage

Manual triggering

Invoke the tool manually by commenting /describe on any PR:

Describe comment{width=512}

After ~30 seconds, the tool will generate a description for the PR:

Describe New{width=512}

If you want to edit configurations, add the relevant ones to the command:

/describe --pr_description.some_config1=... --pr_description.some_config2=...

Automatic triggering

To run the describe automatically when a PR is opened, define in a configuration file:


[azure_devops_server]
pr_commands = [
    "/describe",
    #"/review --pr_reviewer.num_code_suggestions=0",
    #"/update_changelog"
    #"/improve", #dont add this ,mabey has loop exec bug
]


[gitlab]
url = "https://gitlab.com" # URL to the gitlab service
pr_commands = [
    "/describe --pr_description.final_update_message=false",
    "/review --pr_reviewer.num_code_suggestions=0",
    "/improve",
]
handle_push_trigger = false
push_commands = [
    "/describe",
    "/review --pr_reviewer.num_code_suggestions=0",
]

[pr_description]
publish_labels = ...
...
  • The pr_commands lists commands that will be executed automatically when a PR is opened.
  • The [pr_description] section contains the configurations for the describe tool you want to edit (if any).

Configuration options

!!! example “Possible configurations”

publish_labels If set to true, the tool will publish the labels to the PR. Default is true.
publish_description_as_comment If set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the original description. Default is false.
publish_description_as_comment_persistent If set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true.
add_original_user_description If set to true, the tool will add the original user description to the generated description. Default is true.
generate_ai_title If set to true, the tool will also generate an AI title for the PR. Default is false.
extra_instructions Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ..."
enable_pr_type If set to false, it will not show the `PR type` as a text value in the description content. Default is true.
final_update_message If set to true, it will add a comment message [`PR Description updated to latest commit...`](pull/499#issuecomment-1837412176) after finishing calling `/describe`. Default is false.
enable_semantic_files_types If set to true, "Changes walkthrough" section will be generated. Default is true.
collapsible_file_list If set to true, the file list in the "Changes walkthrough" section will be collapsible. If set to "adaptive", the file list will be collapsible only if there are more than 8 files. Default is "adaptive".
enable_help_text If set to true, the tool will display a help text in the comment. Default is false.

Markers template

To enable markers, set pr_description.use_description_markers=true. Markers enable to easily integrate user’s content and auto-generated content, with a template-like mechanism.

For example, if the PR original description was:

User content...

## PR Type:
pr_agent:type

## PR Description:
pr_agent:summary

## PR Walkthrough:
pr_agent:walkthrough

The marker pr_agent:type will be replaced with the PR type, pr_agent:summary will be replaced with the PR summary, and pr_agent:walkthrough will be replaced with the PR walkthrough.

Describe markers before{width=512}

→

Describe markers after{width=512}

Configuration params:

  • use_description_markers: if set to true, the tool will use markers template. It replaces every marker of the form pr_agent:marker_name with the relevant content. Default is false.
  • include_generated_by_header: if set to true, the tool will add a dedicated header: ‘Generated by Code Review Agent at …’ to any automatic content. Default is true.

Usage Tips

!!! tip “Automation” - When you first install , the default mode for the describe tool is: pr_commands = ["/describe", ...] meaning the describe tool will run automatically when any PR be created, with the default configurations.

  • Markers are an alternative way to control the generated description, to give maximal control to the user. If you set:
pr_commands = ["/describe --pr_description.use_description_markers=true", ...]

the tool will replace every marker of the form pr_agent:marker_name in the PR description with the relevant content, where marker_name is one of the following: * type: the PR type. * summary: the PR summary. * walkthrough: the PR walkthrough.

  • Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all.