Skip to main content

Describe

Overview​

Generate a PR title, type, summary, code walkthrough and labels.

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

/describe

Example usage​

Manual triggering​

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

Describe comment

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

Describe New

While a large PR's chunks run, the temporary Preparing PR description... comment is rewritten in place, for example Preparing PR description... analyzed 2 of 3 chunks; once every chunk has settled, , 1 chunk failed is added if a chunk gave up. This needs config.publish_output_progress and a provider that can edit and remove comments; single-chunk runs keep the plain placeholder.

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

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

From the CLI, save the generated description and token usage as JSON for a later CI step:

pr-agent --pr_url https://github.com/org/repo/pull/123 --json-output describe.json describe

The JSON file is written after the description is assembled. Place --json-output before describe or describe_pr; it works with --pr_url or with plain-diff input (--stdin or --diff-file).

Automatic triggering​

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

[github_app]
pr_commands = [
    "/describe",
    ...
]

[pr_description]
publish_labels = true
...
  • 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 command you want to edit (if any).

File walkthrough summaries​

On providers that support the HTML walkthrough, short file summaries appear on a new line after the filename. When detailed changes are available, expanding the file entry reveals them while the short summary stays visible when collapsed. GitLab descriptions no longer use description-list indentation for these summaries.

The description reader can extract file summaries from both the current and legacy walkthrough formats. If separate PR-Agent installations generate walkthroughs and reuse their file summaries (for example, /describe and /review), upgrade them together; older readers cannot extract file summaries from the new format.

Preserving the original user description​

By default, PR-Agent tries to preserve your original PR description by placing it above the generated content. This requires including your description during the initial PR creation.

"PR-Agent removed the original description from the PR. Why"?

From our experience, there are two possible reasons:

  • If you edit the description while the automated command is running, a race condition may occur, potentially causing your original description to be lost. Hence, create a description before launching the PR.

  • When updating a description previously generated by PR-Agent, /describe preserves text after the first recognized ### **User description** heading until the next recognized boundary heading, trimming surrounding whitespace and a trailing ___. If no boundary heading follows, it stops at the first ___ substring, or at the end if none is present, and trims surrounding whitespace. If the generated description has no recognized ### **User description** heading, add that heading before your manual text; otherwise that text can be lost on the next body update.

    Boundary headings are lines starting with ### **PR type**, ### **PR description**, ### **PR labels**, ### **Type**, ### **Description**, ### **Labels**, or ### 🤖 Generated by PR Agent, matched case-insensitively outside fenced code blocks. Manual headings with these prefixes also end preservation, even if more text follows the prefix. Keep manual edits inside these boundaries; edits to generated sections are replaced.

Describe comment

Flowchart Support​

The /describe command includes a Mermaid flowchart summarizing the main PR changes on providers that support gfm_markdown.

This option is enabled by default via the pr_description.enable_pr_diagram param.

The direction of the diagram adapts to its shape. A diagram whose longest chain of nodes exceeds pr_description.pr_diagram_direction_threshold is drawn top-down rather than left-to-right, so that wide diagrams are not scaled down until they become unreadable. Set pr_description.pr_diagram_direction to LR or TD to pin the direction instead.

Configuration options​

The descriptions below explain each option's behavior. See the relevant sections in configuration.toml for the authoritative default values.

Possible configurations
publish_labels If set to true, the command will publish labels to the PR.
publish_description_as_comment If set to true, the command will publish the description as a comment to the PR. If false, it will overwrite the original description.
publish_description_as_comment_persistent If set to true and `publish_description_as_comment` is true, the command will publish the description as a persistent comment to the PR.
add_original_user_description If set to true, the command will add the original user description to the generated description.
generate_ai_title If set to true, the command will also generate an AI title for the PR.
extra_instructions Optional extra instructions to the command. 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.
enable_pr_description If set to false, the AI-generated summary section will not be requested from the model, nor shown in the description content. The other sections (diagram, changes walkthrough) are unaffected.
final_update_message If set to true, it will add a comment message [`PR Description updated to latest commit...`](https://github.com/the-pr-agent/pr-agent/pull/499#issuecomment-1837412176) after finishing calling `/describe`.
enable_semantic_files_types If set to true, "Changes walkthrough" section will be generated.
file_table_collapsible_open_by_default Controls whether the file list in the "Changes walkthrough" section is initially open or closed.
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 when the number of files exceeds collapsible_file_list_threshold.
enable_large_pr_handling If set to true, in case of a large PR the command will make several calls to the AI and combine them to be able to cover more files.
enable_help_text If set to true, the command will display a help text in the comment.
enable_pr_diagram If set to true, the command will generate a Mermaid flowchart summarizing the main pull request changes. This field remains empty if not applicable.
pr_diagram_direction Direction of the generated Mermaid flowchart: adaptive, LR or TD. With adaptive, the direction is chosen from the shape of the diagram.
pr_diagram_direction_threshold With adaptive direction, a diagram whose longest chain exceeds this many nodes is drawn top-down instead of left-to-right.

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

## PR Diagram:
pr_agent:diagram

The marker pr_agent:type will be replaced with the PR type, pr_agent:summary will be replaced with the PR summary, pr_agent:walkthrough will be replaced with the PR walkthrough, and pr_agent:diagram will be replaced with the flowchart (if enabled).

Describe markers before

becomes

Describe markers after

Configuration params:

  • use_description_markers: if set to true, the command 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: only applies when use_description_markers is true. If true (default), the command adds a 'Generated by PR Agent at ...' header to automatic content when the provider supplies a head commit SHA, otherwise the header is 'Generated by PR Agent' (or uses config.bot_display_name when configured). If false, no header is added.
  • diagram: if present as a marker, will be replaced by the PR flowchart (if enabled).

Custom labels​

The default labels of the describe command are quite generic, since they are meant to be used in any repo: [Bug fix, Tests, Enhancement, Documentation, Other].

You can define custom labels that are relevant for your repo and use cases. Custom labels can be defined in the PR-Agent host configuration, or directly in the repo's labels page. The host configuration options cannot be set from the repository's .pr_agent.toml or comment arguments.

Make sure to provide proper title, and a detailed and well-phrased description for each label, so the command will know when to suggest it. Each label description should be a conditional statement, that indicates if to add the label to the PR or not, according to the PR content.

Auto-remove custom label when no longer relevant

If the custom label is no longer relevant, it will be automatically removed from the PR by running the generate_labels command or the describe command.

Handle custom labels from a configuration file​

Example for a custom labels configuration setup in the PR-Agent host configuration:

[config]
enable_custom_labels=true


[custom_labels."sql_changes"]
description = "Use when a PR contains changes to SQL queries"

[custom_labels."test"]
description = "use when a PR primarily contains new tests"

...

Handle custom labels from the Repo's labels page​

You can also control the custom labels that will be suggested by the describe command from the repo's labels page:

  • GitHub : go to https://github.com/{owner}/{repo}/labels (or click on the "Labels" tab in the issues or PRs page)
  • GitLab : go to https://gitlab.com/{owner}/{repo}/-/labels (or click on "Manage" -> "Labels" on the left menu)

Now add/edit the custom labels. they should be formatted as follows:

  • Label name: The name of the custom label.
  • Description: Start the description of with prefix pr_agent:, for example: pr_agent: Description of when AI should suggest this label.

Examples for custom labels:

  • Main topic:performance - pr_agent:The main topic of this PR is performance
  • New endpoint - pr_agent:A new endpoint was added in this PR
  • SQL query - pr_agent:A new SQL query was added in this PR
  • Dockerfile changes - pr_agent:The PR contains changes in the Dockerfile
  • ...

The description should be comprehensive and detailed, indicating when to add the desired label. For example: Add native custom labels

Usage Tips​

Automation

When you first install PR-Agent app, the default mode for the describe command is:

pr_commands = ["/describe", ...]

meaning the describe command will run automatically on every PR, 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 command 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 command will not alter the description at all.