repomatic.github.pr_body module

Assemble the body of an automated pull request or issue.

render_pr() renders a pull request’s title, body and commit message from a PrTemplate, filling each argument the template declares from the CLI, the environment or the GitHub API. The body ends on a collapsible <details> block of workflow metadata, read from an injected Metadata instance (the injection keeps this module import-cycle-free: Metadata pulls in half the package).

build_pr_body() and fit_github_body() keep a body within GitHub’s size limit, and temp_body_file() hands it to gh as a file.

repomatic.github.pr_body.GITHUB_BODY_MAX_CHARS = 65536

GitHub’s maximum PR and issue body size, in UTF-16 code units.

GitHub’s API rejects longer bodies outright, so an oversized body has to be trimmed before it is posted. The obvious trim is the wrong one: cutting the end (what a plain body[:65536] does) drops whatever sits last, which here is the refresh tip, the metadata block and the attribution footer: the navigational parts a reader needs most when a report is too long to read. build_pr_body() (PRs) and fit_github_body() (issues) therefore trim the leading content instead, so the tail always survives.

exception repomatic.github.pr_body.TemplateArgumentError

Bases: ValueError

A template argument that nothing supplied a value for.

class repomatic.github.pr_body.PrContent(title, body, commit_message)

Bases: object

A rendered pull request, ready for gh and for the commit.

title: str

The pull request title, empty when no template supplies one.

body: str

The markdown body, metadata block and attribution footer included.

commit_message: str

The commit message, empty when no template supplies one.

repomatic.github.pr_body.generate_pr_metadata_block(md, docs_url='', docs_name='')

Generate a collapsible metadata block from CI context.

Reads the GITHUB_* environment context from md and returns a markdown <details> block listing the workflow metadata fields.

Parameters:

• md (Metadata) – The Metadata instance to read CI context from.

• docs_url (str) – Optional deep link to the job’s section of the hosted workflows reference, rendered as the leading Documentation entry. Comes from the template’s docs: frontmatter field (see docs_url).

• docs_name (str) – Label for the documentation link, usually the template (operation) name. Without it the raw URL renders as an autolink.

Return type:

str

Returns:

A markdown string with the metadata block.

repomatic.github.pr_body.generate_refresh_tip(md)

Generate a tip admonition inviting users to refresh the PR manually.

Reads the repository URL and GITHUB_WORKFLOW_REF from md to build the workflow dispatch URL.

Parameters:

md (Metadata) – The Metadata instance to read CI context from.

Return type:

str

Returns:

A GitHub-flavored markdown [!TIP] blockquote, or an empty string if the workflow reference is unavailable.

repomatic.github.pr_body.build_pr_body(prefix, metadata_block, refresh_tip='')

Concatenate prefix, refresh tip, and metadata block into a PR body.

The metadata_block already includes the attribution footer (appended automatically by render_template()); the refresh_tip comes pre-rendered from generate_refresh_tip() (empty to omit it).

Bodies over GITHUB_BODY_MAX_CHARS have their prefix trimmed to fit, replacing the dropped lines with a caution admonition, so the refresh tip, metadata block, and attribution footer always survive. Left alone, GitHub-side truncation would chop the body from the end instead.

Parameters:

• prefix (str) – Content to prepend before the metadata block. Can be empty.

• metadata_block (str) – The collapsible metadata block from generate_pr_metadata_block(), with footer.

• refresh_tip (str) – Pre-rendered refresh-tip admonition, or empty.

Return type:

str

Returns:

The complete PR body string.

repomatic.github.pr_body.fit_github_body(body)

Trim an oversized issue or pull-request body, keeping the footer.

The build_pr_body() counterpart for bodies rendered straight from a footer-carrying template (broken-links report, setup guide), and the safety net upsert_pr() runs over an explicit --body that never went through build_pr_body(). The GitHub API rejects oversized bodies outright (gh issue create, gh issue edit and gh pr create all fail), so the content above the attribution footer is trimmed on line boundaries, with a caution admonition marking the cut.

Parameters:

body (str) – The rendered body, attribution footer included.

Return type:

str

Returns:

The body unchanged when it fits, else trimmed to fit.

repomatic.github.pr_body.temp_body_file(body)

Materialize a rendered body as a temporary file, then remove it.

The gh CLI takes a body only through --body-file, so every write path against an issue or a pull request needs one on disk. Owning the temp file at this layer keeps callers working in the currency they actually produce (rendered markdown) instead of each repeating the same write / try / unlink envelope.

Return type:

Generator[Path, None, None]

repomatic.github.pr_body.render_pr(md, config, *, template=None, prefix='', extra_args=None, version=None, part=None, pr_ref=None)

Render a pull request’s title, body and commit message.

The rendering core shared by pr-body (which emits the three as step outputs for external consumption) and pr-sync (which feeds them straight to upsert_pr(), skipping the $GITHUB_OUTPUT round-trip and its step-output ceiling entirely).

Parameters:

• md (Metadata) – CI context. One instance for the whole render, so the review steps, the repo_url argument and the metadata block read the same state.

• config (Config) – The resolved [tool.repomatic] configuration.

• template (PrTemplate | None) – The template to render, or None for a body made of prefix and the metadata block alone.

• prefix (str) – Content placed before the rendered template.

• extra_args (Mapping[str, str] | None) – Template arguments given explicitly. They win over every source repomatic knows, so a caller can feed any name.

• version (str | None) – The release version, read from the bumpversion configuration when None.

• part (str | None) – The version part a bump template names.

• pr_ref (str | None) – The pull request reference a squash-merge report names.

Return type:

PrContent

Returns:

The title and commit message are empty when no template supplies them.

Raises:

TemplateArgumentError – When nothing supplies an argument the template declares.