feat(prsync): recreate pull requests, discussion, and reviews at the destination (#44)

* feat(prsync): body composition with markers and mention safety

* feat(vcs): pull request writer and conversation interfaces

* feat(state): record mirrored pull requests

* feat(github): create, update, and close destination pull requests

* feat(github): read and write pull request conversation

* feat(prsync): destination pull request lifecycle and conversation

* feat(gitsync): wire destination pull request mirroring

* docs: destination pull request mirroring

---------

Co-authored-by: Anmol Nagpal <ianmolnagpal@gmail.com>

Author: clouddrove-ci

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.2.0] - 2026-08-19
 
 ### Added
+- `git-sync` can recreate pull requests at the destination. With `pull_requests.mirror_objects` on a mirror, each open source pull request becomes a real destination pull request, updated on every run, carrying its discussion comments, inline review comments anchored to the diff, review verdicts, and labels. A merged source pull request closes the destination one with a comment naming the source merge commit rather than merging it, because a destination merge would create a different commit that the branch mirror then overwrites. Review verdicts are mirrored as attributed text, never as real approvals, so a mirror cannot satisfy branch protection that no human satisfied. Mentions and issue references in mirrored text are neutralised, so mirrored content never notifies a destination account or cross links an unrelated issue. Everything SyncerD writes carries a hidden marker, so a lost state file causes re-inspection rather than duplicate pull requests, and only comments SyncerD wrote are ever edited or deleted. With `mirror_objects` on, every mirrored pull request gets a `branch_prefix` branch rather than fork heads alone, so a destination pull request has one uniform head name. GitHub source and destination for now; other providers are rejected at startup
 - `git-sync` can mirror the commits behind open pull requests. A pull request opened from a fork has no branch in the source repository, so its commits previously reached no destination at all; with `pull_requests.enabled` on a mirror, the head is pushed as an ordinary branch under `branch_prefix` (default `syncerd/pr/<number>`), and the default mirror push mode prunes it once the pull request closes. A head that lives in the source repository already arrives with the ordinary branch mirror and gets no second copy. A repository whose own branches sit under the prefix is refused rather than silently overwritten, and one unreachable fork head is a warning rather than a failed repository. Off by default: a fork head is third party code, and a destination that builds on branch push would run it. GitHub sources only for now; the pull request objects themselves are not recreated at the destination yet
 
 ### Fixed

README.md

@@ -380,6 +380,8 @@ export SYNCERD_GIT_GL_TOKEN=your-gitlab-token
 
 **Pull request heads (opt in):** set `pull_requests.enabled: true` on a mirror and the commits behind each open pull request opened from a **fork** are pushed to the destination as a branch, default `syncerd/pr/<number>`. Without it those commits reach the destination nowhere, since a fork pull request has no branch in the source repository. A pull request opened from a source branch already mirrors under its own name and gets no second copy. The pull request itself is not recreated at the destination yet. Off by default because a fork head is third-party code, and a destination that builds on branch push would run it: read the security note in [docs/git-sync-runbook.md](docs/git-sync-runbook.md#mirroring-pull-request-heads) before enabling it.
 
+**Mirrored pull requests (opt in):** add `pull_requests.mirror_objects: true` and each open source pull request is recreated at the destination as a real pull request, kept in step on every run, with its discussion, inline review comments, and review verdicts. The source is the single authority; nothing written at the destination flows back. A merged source pull request is closed at the destination with a note naming the merge commit, never merged there, because a destination merge would diverge from the mirrored base branch. Review verdicts are mirrored as attributed text rather than real approvals. Mentions and issue references in mirrored text are neutralised so a mirror never notifies or cross links anyone. GitHub on both ends for now.
+
 Run with `--dry-run` to print the ref changes each mirror would make, per repository, without creating, pushing, or deleting anything.
 
 **Limitations:**

docs/git-sync-runbook.md

@@ -623,8 +623,56 @@ Under the default `mirror` push mode the branch disappears from the destination
 on the first run after the pull request closes: the source stops listing it, and
 prune removes what the source no longer has.
 
-The pull request object itself, its title, discussion, and reviews, is not
-recreated at the destination. Only the commits are.
+### Recreating the pull requests themselves
+
+Set `mirror_objects` and each open source pull request is recreated at the
+destination as a real pull request, updated on every run, with its discussion,
+its inline review comments, and its review verdicts:
+
+```yaml
+      pull_requests:
+        enabled: true
+        mirror_objects: true      # default false, requires enabled
+        comments: true            # default true once mirror_objects is on
+        reviews: true             # default true once mirror_objects is on
+        labels: true              # default true
+```
+
+With `mirror_objects` on, **every** mirrored pull request gets a
+`branch_prefix` branch, including one whose head is already a branch of the
+source repository. A destination pull request has to name one head branch, and
+a uniform name is what keeps the mapping simple. With it off, the P1 rule
+stands: fork heads only.
+
+**A merged source pull request is closed at the destination, not merged.** A
+merge performed at the destination would create a merge commit that differs
+from the source's, and the branch mirror then force overwrites it, so the
+destination would report a merge whose commit no longer exists. SyncerD closes
+the pull request instead and comments naming the source merge commit, which by
+then genuinely is on the destination's base branch.
+
+**Review verdicts are mirrored as text, never as real approvals.** An approval
+posted by SyncerD's token would be a review nobody performed, and on a
+destination with required approvals it would satisfy a rule no human satisfied.
+
+**Mentions and issue references are neutralised.** `@someone` in a mirrored
+body would otherwise notify whichever destination account owns that handle, and
+`#123` would cross link to an unrelated destination issue. Both are rewritten
+to render identically and link to nothing. Text inside fenced code blocks is
+left byte for byte.
+
+Everything SyncerD writes carries a hidden marker. That is how a later run
+updates its own comments in place instead of posting duplicates, and how a
+destination pull request is re-identified after a lost state file, so losing
+state causes re-inspection rather than a second copy of everything.
+
+Only comments SyncerD wrote are ever edited or deleted. A comment written by a
+person at the destination is left alone, even though the source is the
+authority: the source is authority over what it published, not over what
+somebody else said.
+
+Today this needs GitHub on both ends. Any other destination is rejected at
+startup.
 
 **Read this before enabling it.** A fork pull request head is code written by
 anyone who can open a pull request against the source. Turning this on pushes

internal/config/git.go

@@ -124,6 +124,45 @@ type PullRequestsConfig struct {
 	Enabled      bool     `mapstructure:"enabled"`
 	BranchPrefix string   `mapstructure:"branch_prefix"`
 	States       []string `mapstructure:"states"`
+
+	// MirrorObjects recreates each source pull request as a real pull
+	// request at the destination. It also makes every mirrored pull
+	// request get a branch under BranchPrefix, including one whose head
+	// lives in the source repository, so a destination pull request always
+	// has one uniform head name to point at.
+	MirrorObjects bool `mapstructure:"mirror_objects"`
+
+	// The bool pointers distinguish unset from an explicit false, so the
+	// defaults below apply only where the operator said nothing.
+	Comments *bool `mapstructure:"comments"`
+	Reviews  *bool `mapstructure:"reviews"`
+	Labels   *bool `mapstructure:"labels"`
+}
+
+// CommentsOrDefault reports whether discussion and review comments are
+// mirrored. On by default once objects are mirrored: a pull request with no
+// conversation is a poor mirror of one that has a conversation.
+func (p PullRequestsConfig) CommentsOrDefault() bool {
+	if p.Comments == nil {
+		return p.MirrorObjects
+	}
+	return *p.Comments
+}
+
+// ReviewsOrDefault reports whether review verdicts are mirrored as text.
+func (p PullRequestsConfig) ReviewsOrDefault() bool {
+	if p.Reviews == nil {
+		return p.MirrorObjects
+	}
+	return *p.Reviews
+}
+
+// LabelsOrDefault reports whether labels are applied at the destination.
+func (p PullRequestsConfig) LabelsOrDefault() bool {
+	if p.Labels == nil {
+		return true
+	}
+	return *p.Labels
 }
 
 // BranchPrefixOrDefault reports the effective branch prefix.
@@ -321,6 +360,9 @@ func (c *Config) ValidateGitSync() error {
 		// A disabled block is not validated. Its fields have no effect,
 		// and rejecting a stale value in one would block a run that does
 		// not read it.
+		if m.PullRequests.MirrorObjects && !m.PullRequests.Enabled {
+			return fmt.Errorf("git.mirrors[%d].pull_requests.mirror_objects is set but enabled is not; the destination pull request needs the head branch that enabled mirrors", i)
+		}
 		if m.PullRequests.Enabled {
 			if err := vcs.ValidateBranchPrefix(m.PullRequests.BranchPrefixOrDefault()); err != nil {
 				return fmt.Errorf("git.mirrors[%d].pull_requests: %w", i, err)

internal/config/git_test.go

@@ -363,3 +363,34 @@ func TestBranchPrefixOrDefault(t *testing.T) {
 		t.Errorf("BranchPrefixOrDefault = %q, want mirrored/pr", got)
 	}
 }
+
+func TestValidateGitSyncRejectsMirrorObjectsWithoutEnabled(t *testing.T) {
+	cfg := &Config{Git: validGit()}
+	cfg.Git.Mirrors[0].PullRequests = PullRequestsConfig{MirrorObjects: true}
+	cfg.Git.ApplyDefaults()
+	err := cfg.ValidateGitSync()
+	if err == nil || !strings.Contains(err.Error(), "mirror_objects") {
+		t.Fatalf("expected a mirror_objects error, got %v", err)
+	}
+}
+
+func TestPullRequestSwitchDefaults(t *testing.T) {
+	off := PullRequestsConfig{Enabled: true}
+	if off.CommentsOrDefault() || off.ReviewsOrDefault() {
+		t.Error("comments and reviews follow mirror_objects, which is off here")
+	}
+	if !off.LabelsOrDefault() {
+		t.Error("labels default on")
+	}
+
+	on := PullRequestsConfig{Enabled: true, MirrorObjects: true}
+	if !on.CommentsOrDefault() || !on.ReviewsOrDefault() {
+		t.Error("comments and reviews default on once objects are mirrored")
+	}
+
+	no := false
+	explicit := PullRequestsConfig{Enabled: true, MirrorObjects: true, Comments: &no, Reviews: &no, Labels: &no}
+	if explicit.CommentsOrDefault() || explicit.ReviewsOrDefault() || explicit.LabelsOrDefault() {
+		t.Error("an explicit false must win over the default")
+	}
+}

internal/gitsync/build.go

@@ -148,6 +148,29 @@ func BuildMirrors(cfg *config.GitConfig) ([]Mirror, *Redactor, error) {
 			}
 		}
 
+		// Mirroring the objects needs a destination that can write them,
+		// and, when the conversation is included, both sides able to read
+		// and write comments. Refusing here beats a run that quietly
+		// mirrors branches and calls it done.
+		var destPRs vcs.PullRequestWriter
+		var sourceConv, destConv vcs.PullRequestConversation
+		if mc.PullRequests.MirrorObjects {
+			destPRs, ok = dst.(vcs.PullRequestWriter)
+			if !ok {
+				return nil, nil, fmt.Errorf("mirror %q: pull_requests.mirror_objects is set but destination provider %q (type %q) cannot write pull requests; GitHub is supported today and the remaining provider types arrive in a later release", mc.Name, mc.Destination, dst.Type())
+			}
+			if mc.PullRequests.CommentsOrDefault() || mc.PullRequests.ReviewsOrDefault() {
+				sourceConv, ok = src.(vcs.PullRequestConversation)
+				if !ok {
+					return nil, nil, fmt.Errorf("mirror %q: pull request comments are enabled but source provider %q (type %q) cannot read them; set comments: false and reviews: false, or wait for that provider", mc.Name, mc.Source, src.Type())
+				}
+				destConv, ok = dst.(vcs.PullRequestConversation)
+				if !ok {
+					return nil, nil, fmt.Errorf("mirror %q: pull request comments are enabled but destination provider %q (type %q) cannot write them; set comments: false and reviews: false, or wait for that provider", mc.Name, mc.Destination, dst.Type())
+				}
+			}
+		}
+
 		mirrors = append(mirrors, Mirror{
 			Name:         mc.Name,
 			Source:       lister,
@@ -166,9 +189,16 @@ func BuildMirrors(cfg *config.GitConfig) ([]Mirror, *Redactor, error) {
 			CreateMissing: mc.CreateMissingOrDefault(),
 			Visibility:    mc.Visibility,
 			SourcePRs:     sourcePRs,
+			DestPRs:       destPRs,
+			SourceConv:    sourceConv,
+			DestConv:      destConv,
 			PullRequests: PRSyncConfig{
-				Enabled:      mc.PullRequests.Enabled,
-				BranchPrefix: mc.PullRequests.BranchPrefixOrDefault(),
+				Enabled:       mc.PullRequests.Enabled,
+				BranchPrefix:  mc.PullRequests.BranchPrefixOrDefault(),
+				MirrorObjects: mc.PullRequests.MirrorObjects,
+				Comments:      mc.PullRequests.CommentsOrDefault(),
+				Reviews:       mc.PullRequests.ReviewsOrDefault(),
+				Labels:        mc.PullRequests.LabelsOrDefault(),
 			},
 		})
 	}

internal/gitsync/build_test.go

@@ -313,3 +313,41 @@ func TestBuildMirrorsLeavesPullRequestsOffByDefault(t *testing.T) {
 		t.Error("a mirror with no pull_requests block must not wire a lister")
 	}
 }
+
+func TestBuildMirrorsWiresPullRequestObjects(t *testing.T) {
+	cfg := buildableConfig()
+	// GitHub on both ends: the only pair that can write pull requests today.
+	cfg.Mirrors[0].Destination = "gh2"
+	cfg.Providers = append(cfg.Providers, config.GitProviderConfig{
+		Name: "gh2", Type: "github", Owner: "mirror", Token: "ghp_token_value_two",
+	})
+	cfg.Mirrors[0].PullRequests = config.PullRequestsConfig{Enabled: true, MirrorObjects: true}
+
+	mirrors, _, err := BuildMirrors(cfg)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	m := mirrors[0]
+	if !m.PullRequests.MirrorObjects {
+		t.Error("MirrorObjects was not carried through")
+	}
+	if m.DestPRs == nil {
+		t.Error("a GitHub destination must be wired as a pull request writer")
+	}
+	if m.SourceConv == nil || m.DestConv == nil {
+		t.Error("conversation endpoints must be wired when comments default on")
+	}
+	if !m.PullRequests.Comments || !m.PullRequests.Reviews || !m.PullRequests.Labels {
+		t.Errorf("switches = %+v", m.PullRequests)
+	}
+}
+
+func TestBuildMirrorsRejectsADestinationThatCannotWritePullRequests(t *testing.T) {
+	cfg := buildableConfig()
+	cfg.Mirrors[0].PullRequests = config.PullRequestsConfig{Enabled: true, MirrorObjects: true}
+
+	_, _, err := BuildMirrors(cfg)
+	if err == nil || !strings.Contains(err.Error(), "mirror_objects") {
+		t.Fatalf("a GitLab destination cannot write pull requests yet, want that error, got %v", err)
+	}
+}