Generate Labels

Overview

The generate_labels command scans the PR code changes and generates custom labels for the PR based on the content and context of the changes.

It can be invoked manually by commenting on any PR:

/generate_labels

Example usage

Invoke the command manually by commenting /generate_labels on any PR.

The command will analyze the PR and add appropriate labels.

For local or CI workflows that need label suggestions without a hosting-provider token, pass a unified diff and write the filtered labels to a JSON artifact:

python -m pr_agent.cli --diff-file changes.diff --json-output labels.json generate_labels

The JSON result contains a labels list and a usage object (empty when token usage is unavailable). Only model-generated labels that pass the existing allowlist are included; labels already on a hosted PR are not included. A PR without analyzable changes produces an empty list. This option does not change the normal label publication behavior. Check the command's exit status before consuming the artifact: a failed run does not delete a previous JSON file.

Configuration options

The generate_labels command uses configurations from the [pr_description] section for custom labels.

Enabling custom labels

To use custom labels, you need to enable them in the configuration:

Set these options in the PR-Agent host configuration. Repository .pr_agent.toml files and comment arguments cannot change them.

[config]
enable_custom_labels = true

Defining custom labels

You can define your own custom labels in the [custom_labels] section. See the custom_labels.toml file for examples.

Example configuration:

[custom_labels."Bug fix"]
description = "A fix for a bug in the codebase"

[custom_labels."Feature"]
description = "A new feature or enhancement"

[custom_labels."Documentation"]
description = "Documentation changes only"

[custom_labels."Tests"]
description = "Adding or modifying tests"

[custom_labels."Refactoring"]
description = "Code refactoring without functional changes"

How labels are applied

1. The command analyzes the PR diff and commit messages
2. It uses AI to determine which labels best match the PR content
3. Labels are automatically applied to the PR (if the git provider supports it)
4. If labels cannot be applied directly, they are published as a comment

Both /generate_labels and /describe filter model-generated labels before publishing. The allowed set contains the built-in PR types (Bug fix, Tests, Enhancement, Documentation, Other) plus the configured custom label names when custom labels are enabled. With custom labels enabled but no custom set configured, the default set also includes Bug fix with tests. Matching ignores case, and unknown generated labels are dropped with a warning. Existing human-added labels are preserved and are not restricted by this filter.

Prompt enum keys such as bug_fix and RELEASE_READY are resolved to their allowed display names, ignoring case. If a nonempty model response contains only rejected labels, /generate_labels leaves the current labels unchanged. An explicit labels: [] response retains the existing behavior of clearing old bot-owned labels while preserving human-added labels.

If the current labels cannot be read, /generate_labels skips publication and records the command as failed. A known provider failure while publishing labels also marks the command as failed. With config.propagate_command_errors = true, these failures raise an error after temporary-comment cleanup.

A successful provider acknowledgement means its label operation completed normally; it does not verify the final remote label set. Providers apply labels differently, and a failure can leave some changes applied. The command does not retry or roll back those changes. Labels generated by /describe and /review remain auxiliary to their primary output.

Comparison with /describe labels

The /describe command also generates labels as part of its output. The key differences are:

Feature	/generate_labels	/describe
Purpose	Dedicated label generation	Full PR description with labels
Output	Labels only	Title, summary, walkthrough, and labels
Custom labels	✅ Supported	✅ Supported
Use case	When you only need labels	When you want a complete PR description

Tips

• Use custom labels that match your team's workflow and labeling conventions
• Combine with automation to automatically label PRs when they are opened
• Review the generated labels and adjust custom label descriptions if the AI consistently misclassifies PRs