Push outputs to external sinks
The [push_outputs] feature routes finished command output to external sinks — stdout, a JSONL file, a
generic webhook, Slack, Telegram, or Microsoft Teams — without calling git-provider APIs. It is disabled by default, and is
additive to normal publishing: when a command finishes, its structured result and rendered Markdown
are also emitted to the configured sinks. An effective config.publish_output = false disables both normal publishing
and these sinks. Plain-diff mode forces publishing on to preserve stdout/file output; set
push_outputs.enable = false in the host configuration to disable its extra sinks.
What gets pushed
Each finished command run that produces output emits one record when publishing and the sinks are enabled. The commands that currently emit are:
| Command | type in the record |
|---|---|
/review (and /improve, which runs it) | review |
/describe | describe |
/ask | ask (opt-in with commands) |
/update_changelog | update_changelog (opt-in with commands) |
A record is a JSON object:
{
"type": "review",
"timestamp": "2026-09-08T14:03:21+00:00",
"payload": {},
"pr": {
"url": "https://github.com/org/repo/pull/123",
"provider": "github",
"repo": "org/repo",
"number": 123,
"head_sha": "9fceb02"
},
"markdown": "# PR Reviewer Guide ..."
}
type— which command produced the outputtimestamp— the run completion time, UTC, ISO-8601payload— the structured command resultpr— the command's pull request identity, present when the calling command supplies itpr.url— the pull request page URLpr.provider— the git provider, such asgithub,gitlab, orbitbucketpr.repo— the repository name or pathpr.number— the pull request numberpr.head_sha— the head commit SHAmarkdown— the rendered comment text; present when the command produces one
For /describe, payload.title is the selected title, including the original PR title read when the
command starts if pr_description.generate_ai_title is disabled. When the model output contains a
labels field, payload.labels contains only labels allowed by the configured vocabulary. This field
remains present when pr_description.publish_labels is disabled.
For /ask, payload.question is the user's question and payload.answer is the model's answer (or
the note explaining that no changed files could be analyzed). Its Markdown contains the question
and answer without the PR-only help guide or run-details footer. Inline /ask_line replies are not emitted.
For /update_changelog, payload.path is the selected changelog path and payload.entry contains
only the newly generated Markdown entry, not the full changelog or PR-only commit instructions.
The sink Markdown labels it as a draft. Delivery precedes publishing to the git provider, so a
received record does not confirm that a changelog file was committed successfully.
Configuration
The defaults are defined at the end of the configuration file:
[push_outputs]
enable = false
channels = [] # any of: "stdout", "file", "webhook", "slack", "telegram", "teams"
commands = ["review", "describe"] # opt in to "ask" or "update_changelog" explicitly
file_path = "pr-agent-outputs/reviews.jsonl"
webhook_url = "" # must be an absolute https:// URL
slack_webhook_url = "" # Slack Incoming Webhook; must be an absolute https:// URL
telegram_bot_token = "" # Telegram bot token; host-only secret
telegram_chat_id = "" # destination chat for the Telegram bot
teams_webhook_url = "" # Teams Workflows webhook URL; must be an absolute https:// URL
enable— master switch (defaultfalse). Whenfalse, nothing is emitted.channels— which sinks to use. Use exact registered names as a list/tuple or a comma-separated string; surrounding whitespace is ignored. Nothing is emitted until at least one channel is listed here.commands— which command results to send to those sinks. Defaults toreviewanddescribe;/improvenow runs/review, so its output arrives asreview. Use a list/tuple or comma-separated string of exact names. Addaskorupdate_changelogto opt in to those results. This does not change which commands PR-Agent runs.file_path— the file thefilechannel appends to.webhook_url— the endpoint thewebhookchannel POSTs the generic record to.slack_webhook_url— a Slack Incoming Webhook URL that theslackchannel posts a{"text": ...}payload to.telegram_bot_token— the bot token used by thetelegramchannel. Keep it in host secrets, not a repository file.telegram_chat_id— the chat that receives Telegram messages.teams_webhook_url— a Teams Workflows webhook URL that receives Adaptive Cards from theteamschannel.
For example, a host can set commands = ["review", "ask"] to receive reviews and interactive answers
without sending description or suggestion results. Ask questions and answers may contain private
information; only enable their delivery to trusted, operator-controlled destinations.
When rolling out update_changelog to workers sharing host settings, upgrade all workers before
adding it to commands. Older versions reject unknown command names and skip all sink delivery.
The whole [push_outputs] section is host-only. A repository cannot set these keys:
keys supplied through a repo's local .pr_agent.toml are dropped, and CLI arguments
(--push_outputs.webhook_url=..., --push_outputs={...}) are blocked. This prevents a
pull request from redirecting review output to an attacker-controlled host, reaching
internal endpoints, or appending to arbitrary host files. Configure these values in the
PR-Agent host's own settings.
URL requirements
webhook_url, slack_webhook_url, and teams_webhook_url must be absolute https:// URLs with a host. Any other
value (for example a plain http:// URL or a bare path) is ignored with a warning. Requiring
HTTPS keeps review text, which can quote private code, off plaintext transports. The host is
intentionally not restricted, so self-hosted collectors and Slack-compatible endpoints
(Mattermost, Rocket.Chat) are legitimate targets.
Warnings log the setting name — never the URL value — because a webhook or Slack URL is itself a credential.
Channels
| Channel | Behaviour |
|---|---|
stdout | Prints one JSON line (the record) to stdout. |
file | Appends one JSON line per run (JSONL) to file_path, creating parent directories as needed. |
webhook | POSTs the generic record as JSON to webhook_url (5-second timeout, redirects not followed). |
slack | POSTs {"text": ...} to a Slack Incoming Webhook; the text is the markdown, or the payload JSON when the command produces no markdown, with &, < and > escaped so Slack shows mentions and <url|label> links as plain text, followed by the PR URL when one is present. |
telegram | Sends the markdown, or the payload JSON when no markdown is present, as plain text to telegram_chat_id, followed by the PR URL when one is present. Text is truncated to at most 4096 UTF-16 code units without splitting surrogate pairs; room is reserved for the URL so truncation does not drop it. |
teams | POSTs an Adaptive Card to teams_webhook_url with the command type, markdown output, and a button to the PR when its URL is present. The card is trimmed to Teams' 28 KB message size limit. |
Local channels (stdout, file) run before network channels (webhook, slack, telegram, teams), and network
posts never follow redirects. Each configured destination is attempted independently, so one failure
does not prevent later destinations from receiving the output.
Telegram
Enable the channel in the host's settings and supply the bot token through the host environment:
[push_outputs]
enable = true
channels = ["telegram"]
telegram_chat_id = "<destination-chat-id>"
Set PUSH_OUTPUTS__TELEGRAM_BOT_TOKEN to your bot token in the host's secret environment.
The bot must be able to send messages to the destination chat. Missing credentials skip delivery
with a warning that names only the missing setting.
Requests use the fixed https://api.telegram.org host, a 5-second timeout, and no redirects.
The token is URL-encoded in the request path and is never included in PR-Agent's warning messages.
No Telegram parse mode is set: Markdown syntax is sent as plain text. Longer output is truncated,
not split across messages; other configured channels still receive the complete output.
Error handling
Failures are non-fatal: push_outputs never raises, so a sink outage does not break the review
flow. Exceptions and non-2xx HTTP responses are logged with the destination and only the exception
type or status code, since request error messages can embed the (secret-bearing) URL.
Extending delivery
push_outputs() in pr_agent/algo/run_output.py builds the record once and isolates failures
for each selected destination. The commands deliver from an event loop, so they call
push_outputs_async(), which runs the delivery in a worker thread and awaits it: a slow
destination does not stall the other pull requests the server is handling, and the output
still reaches the sink before the command returns. Delivery strategies live in
pr_agent/algo/output_sinks.py: each implements OutputSink.send(record, cfg), and
create_output_sink() selects the strategy from OUTPUT_SINK_TYPES. Registry order
determines delivery order, with local writes first; duplicate channel entries still result
in a single delivery.
To add a destination, implement its strategy and register it, then add any required host-only settings, documentation, and provider-specific tests. HTTP strategies must validate destinations and preserve the shared HTTPS, timeout, redirect, and secret-safe logging policy. Provider-specific payload formatting belongs in the strategy, so the generic webhook record remains unchanged.
This interface organizes provider implementations; it does not remove the work of maintaining their APIs. Retries, rate limiting, idempotency, and background delivery are separate policy decisions and are not introduced by this structure.