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|detect-squash-merge|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-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|sync-action-pins|sync-bumpversion|sync-dep-sources|sync-gitignore|sync-mailmap|sync-repomatic|sync-runner-images|sync-tool-versions|sync-uv-lock|sync-workflow-pins|unavailable-admonition|unsubscribe-phase1|unsubscribe-phase2|update-dep-graph|update-docs|yanked-admonition]
- Render title, body and commit message from a built-in template, and derive
the branch, labels and draft state from it: the branch defaults to the
template name, labels and draft to its frontmatter.
- --template-file
FILE
- Use an external template file instead of --template, for project-specific
PRs. Same derivations, with the branch defaulting to the file's stem.
- --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
--version / --part / --pr-ref 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 (e.g. 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 when a template is given.
- --title
TEXT
- Pull-request title, when not using a template. Can also be set via the
GHA_PR_TITLE environment variable.
- --body
TEXT
- Rendered markdown body, when not using a template. Can also be set via the
GHA_PR_BODY environment variable.
- --commit-message
TEXT
- Commit message, when not using a template. Can also be set via the
GHA_PR_COMMIT_MESSAGE environment variable.
- --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
- Render title, body and commit message from a built-in template, and derive
the branch, labels and draft state from it: the branch defaults to the
template name, labels and draft to its frontmatter.
- PR_SYNC_TEMPLATE_FILE
- Use an external template file instead of --template, for project-specific
PRs. Same derivations, with the branch defaulting to the file's stem.
- 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
--version / --part / --pr-ref 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 (e.g. 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 when a template is given.
- GHA_PR_TITLE
- Pull-request title, when not using a template. Can also be set via the
GHA_PR_TITLE environment variable.
- PR_SYNC_TITLE
- Pull-request title, when not using a template. Can also be set via the
GHA_PR_TITLE environment variable.
- GHA_PR_BODY
- Rendered markdown body, when not using a template. Can also be set via the
GHA_PR_BODY environment variable.
- PR_SYNC_BODY
- Rendered markdown body, when not using a template. Can also be set via the
GHA_PR_BODY environment variable.
- GHA_PR_COMMIT_MESSAGE
- Commit message, when not using a template. Can also be set via the
GHA_PR_COMMIT_MESSAGE environment variable.
- PR_SYNC_COMMIT_MESSAGE
- Commit message, when not using a template. Can also be set via the
GHA_PR_COMMIT_MESSAGE environment variable.
- 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.
- GHA_PR_ASSIGNEE
- 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.
- 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, or an aborted prompt (Ctrl-C, a declined
confirmation).
- 2
- A usage error: unknown option, invalid value, missing operand, or an
unparsable configuration file.
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"