repomatic pr-sync - Create, refresh or retire an automation PR
repomatic pr-sync [OPTIONS]
Converge a branch and its PR onto whatever the working tree
holds.
Opens the pull request when the tree carries changes, refreshes it
when those changes moved, does nothing at all when the branch already
matches, and closes the PR (deleting the branch) once the changes are
gone.
Idempotent: re-running with an unchanged tree performs no write,
so a workflow re-run never churns the PR or re-triggers its checks.
With --template, the title, body and commit message are rendered
internally and the branch, labels and draft state come from the template and
its frontmatter, so the whole operation is one flag. Without one, pass
--title, --body and --commit-message explicitly.
Works from a detached HEAD: the base falls back to the repository
default branch read from the CI event payload, and any commits the job made
itself are carried through.
Commits the whole tree unless --add-path narrows it. A job that
installs its own linter into the checkout, or runs a package manager that
rewrites a lock file on the way past, wants the narrow form: those writes
are not what the pull request is for.
- --template
[available-admonition|broken-links-issue|bump-version|development-warning|fix-changelog|fix-typos|fix-vulnerable-deps|format-images|format-json|format-markdown|format-pyproject|format-python|format-shell|generated-footer|github-releases|immutable-releases|pr-metadata|prepare-release|refresh-tip|release-notes|release-sync-report|sample-metrics|scan-virustotal|setup-guide|setup-guide-branch-ruleset|setup-guide-cloudflare-pages|setup-guide-cloudflare-r2|setup-guide-dependabot|setup-guide-fork-pr-approval|setup-guide-notifications-pat|setup-guide-pages-source|setup-guide-pypi-trusted-publisher|setup-guide-sha-pinning-required|setup-guide-token|setup-guide-verify|setup-guide-virustotal|squashed-release|sync-action-pins|sync-bumpversion|sync-dep-sources|sync-gitignore|sync-mailmap|sync-repomatic|sync-repomatic-upgrade|sync-runner-images|sync-tool-versions|sync-uv-lock|sync-workflow-pins|unavailable-admonition|unsubscribe-report|update-dep-graph|update-docs|upgrade-invite|yanked-admonition]
- Built-in template to render the content from.
- --template-file
FILE
- Template file to render the content from, instead of --template: markdown
with optional YAML frontmatter, for project-specific content. Set 'footer:
false' in its frontmatter: the metadata block already carries the
attribution footer.
- --template-arg
KEY=VALUE
- Pass an arbitrary key/value pair to the template. Repeat to provide
multiple. Use this to feed template variables not covered by the dedicated
flags. Example: --template-arg channel=Nix.
- --template-arg-file
KEY=PATH
- Read a template value from a file. Repeat to provide multiple. Use this
for a value with no ceiling on its size, like a generated table: a report
travels as a path rather than inline. Example: --template-arg-file
summary=proposal.md.
- --version
TEXT
- Version string passed to the template (like 1.2.0).
- --part
[minor|major]
- Version part passed to the bump-version template.
- --branch
TEXT
- Head branch to create, update or retire. By convention the job ID;
defaults to the template name, or to the stem of the template file.
- --title
TEXT
- Pull-request title, when not using a template.
- --body
TEXT
- Rendered markdown body, when not using a template.
- --commit-message
TEXT
- Commit message, when not using a template.
- --base
TEXT
- Base branch. Defaults to the currently checked-out branch, or to the
repository default branch when the checkout is detached in CI.
- --label
TEXT
- Label to attach, overriding the template's frontmatter labels. Repeat to
provide multiple. Best-effort: a label GitHub refuses warns instead of
failing the command.
- --assignee
TEXT
- Assignee to attach. Repeat to provide multiple. Defaults to the workflow
actor via the ambient GITHUB_ACTOR variable. Best-effort:
github-actions[bot] cannot be assigned and only warns.
- --draft /
--no-draft
- Hold the pull request in draft, overriding the template's frontmatter.
Re-applied on every update, not just at creation, so a PR marked
ready-for-review goes back to draft on the next sync.
- --add-path
TEXT
- Git pathspec limiting what the pull request commits. Repeat to provide
multiple. Defaults to the whole tree, which is right when a job's only
writes are the ones it means to publish; narrow it when the job also
provisions tooling into the checkout, so an installed package or a
rewritten lock file cannot ride along.
- --help /
-h
- Show this message and exit.
- PR_SYNC_TEMPLATE
- Built-in template to render the content from.
- PR_SYNC_TEMPLATE_FILE
- Template file to render the content from, instead of --template: markdown
with optional YAML frontmatter, for project-specific content. Set 'footer:
false' in its frontmatter: the metadata block already carries the
attribution footer.
- PR_SYNC_TEMPLATE_ARGS_CLI
- Pass an arbitrary key/value pair to the template. Repeat to provide
multiple. Use this to feed template variables not covered by the dedicated
flags. Example: --template-arg channel=Nix.
- PR_SYNC_TEMPLATE_ARG_FILES
- Read a template value from a file. Repeat to provide multiple. Use this
for a value with no ceiling on its size, like a generated table: a report
travels as a path rather than inline. Example: --template-arg-file
summary=proposal.md.
- PR_SYNC_VERSION
- Version string passed to the template (like 1.2.0).
- PR_SYNC_PART
- Version part passed to the bump-version template.
- PR_SYNC_BRANCH
- Head branch to create, update or retire. By convention the job ID;
defaults to the template name, or to the stem of the template file.
- PR_SYNC_TITLE
- Pull-request title, when not using a template.
- PR_SYNC_BODY
- Rendered markdown body, when not using a template.
- PR_SYNC_COMMIT_MESSAGE
- Commit message, when not using a template.
- PR_SYNC_BASE
- Base branch. Defaults to the currently checked-out branch, or to the
repository default branch when the checkout is detached in CI.
- PR_SYNC_LABELS
- Label to attach, overriding the template's frontmatter labels. Repeat to
provide multiple. Best-effort: a label GitHub refuses warns instead of
failing the command.
- GITHUB_ACTOR
- Assignee to attach. Repeat to provide multiple. Defaults to the workflow
actor via the ambient GITHUB_ACTOR variable. Best-effort:
github-actions[bot] cannot be assigned and only warns.
- PR_SYNC_ASSIGNEES
- Assignee to attach. Repeat to provide multiple. Defaults to the workflow
actor via the ambient GITHUB_ACTOR variable. Best-effort:
github-actions[bot] cannot be assigned and only warns.
- PR_SYNC_DRAFT
- Hold the pull request in draft, overriding the template's frontmatter.
Re-applied on every update, not just at creation, so a PR marked
ready-for-review goes back to draft on the next sync.
- PR_SYNC_ADD_PATHS
- Git pathspec limiting what the pull request commits. Repeat to provide
multiple. Defaults to the whole tree, which is right when a job's only
writes are the ones it means to publish; narrow it when the job also
provisions tooling into the checkout, so an installed package or a
rewritten lock file cannot ride along.
- PR_SYNC__CLICK_DEFAULT_HELP
- Show this message and exit.
- 0
- Success.
- 1
- A runtime error, an aborted prompt (Ctrl-D), or a declined
confirmation.
- 2
- A usage error: unknown option, invalid value, missing operand, or an
unparsable configuration file.
- 130
- Interrupted with Ctrl-C: the process ends by SIGINT, reported as 130.
Refresh an autofix job's pull request
repomatic pr\-sync \-\-template format\-python
Open a version-bump PR on its conventional branch
repomatic pr\-sync \-\-template bump\-version \-\-part minor \-\-branch minor\-version\-increment
A one-off PR with explicit content
repomatic pr\-sync \-\-branch my\-fix \-\-title "Fix" \-\-body "…" \-\-commit\-message "Fix the thing"