chore(release): 0.2.1 (#47)

* chore(release): 0.2.1

Cuts the Unreleased section carrying destination pull request mirroring,
the four remaining provider implementations, and the fixes from the review
of #46, and repoints the Action examples at the new tag.

Also corrects the 0.2.0 section, which claimed destination pull request
mirroring. That entry was written under Unreleased on the #44 branch, and
by the time it merged the release PR had already renamed that heading to
0.2.0, so a clean auto-merge filed a feature under a tag that never
contained it. The 0.2.0 section now matches what v0.2.0 actually shipped.

* fix(azuredevops): send a username with the PAT on the git transport

pat mode presented an empty username with the PAT as the password. SyncerD
hands git its credential through a helper that prints "username=<value>",
and git reads an empty value as no username at all: it then tries to ask,
terminal prompts are disabled, and every clone and push failed with "could
not read Username", which names nothing about the provider or the config
that produced it.

Azure DevOps ignores the username on this path and authenticates on the
token alone, so the value is free. The organisation name is sent because it
makes the credential legible in a trace without being a secret.

A basic credential carrying a password with no username is now rejected by
the runner as well, so a future provider with the same gap fails with a
sentence that names the cause rather than a bare git error. A bearer
credential still needs no username, and an empty credential, which is what
a local path uses, stays valid.

The REST API path was never affected: it carries the token in an
Authorization header, where an empty username is what Azure DevOps
documents.

---------

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

Author: clouddrove-ci

CHANGELOG.md

@@ -7,10 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 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. Every provider type is supported, see below
 - Pull request mirroring now works for every provider type, in any direction: GitLab, Bitbucket Cloud, Azure DevOps, and AWS CodeCommit join GitHub. Each maps onto the same model, and the runbook carries a table of what each provider cannot represent
 - CodeCommit is in scope after all. It was excluded when the work was planned on the grounds that it had no pull request API worth mirroring, which was wrong: it has a full one, already present in the pinned SDK, and AWS returned the service to general availability on 2025-11-24 after closing it to new customers in 2024
 
+### Fixed
+- `git-sync` could not authenticate to Azure DevOps over git in `pat` mode. The provider presented an empty username with the PAT as the password, and SyncerD hands git its credential through a helper that prints `username=<value>`: git reads an empty value as no username at all, tries to ask for one, and fails with `could not read Username` because terminal prompts are disabled. Azure DevOps ignores the username and authenticates on the token alone, so the organisation name is sent now. A basic credential carrying a password with no username is also rejected up front, where the cause can be named, rather than surfacing as a bare git error. The REST API path was never affected: it sends the token in an Authorization header
+- A destination that cannot reopen a pull request, which is Bitbucket Cloud and CodeCommit, failed on every run once its mirror had been closed by hand. Having decided to leave the pull request closed, the engine still attempted an update on it, which both providers reject, so the failure was recorded before the divergence was: the warning fired every run, a failure was reported every run, and the mirror never settled. The same path ran for a merged source whose destination was already closed whenever new activity advanced its timestamp. An update now runs only while the destination is open, and a recorded divergence is re-checked each run so a destination somebody reopened by hand is picked back up
+- A CodeCommit source served the first run's snapshot forever. Its pull request cache was documented as per run but a provider is built once and reused for every tick of the schedule, so later pull requests were never mirrored, closed ones never closed, and the repository was skipped as unchanged because the same stale set fed the ref fingerprint
+- An Azure DevOps source mirrored each pull request exactly once and then froze it. Azure reports no update timestamp, and standing the creation date in for one meant the engine's watermark always matched, so no later edit, comment, or verdict reached the destination. A source that reports no timestamp is no longer watermarked
+- CodeCommit reported "no reviews" when the underlying call failed, and the caller deletes mirrored comments it no longer sees at the source, so a single throttled call deleted every mirrored review verdict. It surfaces the error instead. For the same reason, a transient failure posting an anchored comment is no longer treated as a rejected anchor, which would have downgraded it to a plain comment permanently
+- CodeCommit could not find a destination pull request that had been closed, so a lost state file created a second one for the same branch. GitLab anchored every comment on a deleted line to line 0 on the wrong side of the diff, and read its transient `locked` state as closed, which closed the destination and posted "closed without merging" moments before the source became merged. Bitbucket dropped the draft flag on update and could not find a superseded pull request. GitHub reported no base SHA, so every inline comment mirrored to GitLab or CodeCommit, which both require one, silently became a plain comment. Azure DevOps counted a description limit in bytes rather than characters, truncating non-ASCII text to roughly a third of the allowed length
+- Turning `comments` or `reviews` off deleted everything previously mirrored in that category. Deletion is now scoped to the categories a run actually listed
+
 ### Changed
 - `vcs.PullRequestSpec` carries `SyncLabels`, so a provider can tell "the source has no labels", where a destination label should be removed, from "label mirroring is off", where a label somebody added at the destination must be left alone. Labels are now reconciled rather than only added: one removed at the source is removed at the destination
 - `vcs.PullRequestWriter` closes a pull request but no longer reopens one. Bitbucket Cloud has no reopen endpoint and CodeCommit permits only the `OPEN` to `CLOSED` transition, so reopening is now an optional `vcs.PullRequestReopener` capability. A destination that lacks it leaves the pull request closed, warns once, and records the divergence rather than opening a second pull request for the same work or retrying on every run
@@ -19,7 +31,6 @@ 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

@@ -121,7 +121,7 @@ Requires Go 1.23+ to build from source.
 Add SyncerD to your workflow:
 
 ```yaml
-- uses: clouddrove/syncerd@v0.2.0
+- uses: clouddrove/syncerd@v0.2.1
   with:
     config: syncerd.yaml
     once: "true"
@@ -139,7 +139,7 @@ For **AWS ECR**, add `aws-actions/configure-aws-credentials` before SyncerD and
     role-to-assume: arn:aws:iam::123456789012:role/syncerd
     aws-region: eu-west-1
 
-- uses: clouddrove/syncerd@v0.2.0
+- uses: clouddrove/syncerd@v0.2.1
   with:
     config: syncerd.yaml
 ```
@@ -157,7 +157,7 @@ steps:
       username: ${{ github.actor }}
       password: ${{ secrets.GITHUB_TOKEN }}
 
-  - uses: clouddrove/syncerd@v0.2.0
+  - uses: clouddrove/syncerd@v0.2.1
     env:
       DOCKER_CONFIG: /github/workspace/.docker     # same directory, path inside the container
     with:
@@ -181,7 +181,7 @@ steps:
 Since the default push mode deletes destination refs that are absent at the source, **run once with `dry-run: "true"` before trusting a new mirror config**:
 
 ```yaml
-- uses: clouddrove/syncerd@v0.2.0
+- uses: clouddrove/syncerd@v0.2.1
   with:
     command: git-sync
     config: syncerd.yaml
@@ -195,7 +195,7 @@ Since the default push mode deletes destination refs that are absent at the sour
 Once the dry run output looks right, drop `dry-run` (or set it to `"false"`) to let it write for real:
 
 ```yaml
-- uses: clouddrove/syncerd@v0.2.0
+- uses: clouddrove/syncerd@v0.2.1
   with:
     command: git-sync
     config: syncerd.yaml

internal/gitsync/runner.go

@@ -334,6 +334,14 @@ func rejectURLCredentials(raw string) error {
 // newline silently truncates the value and turns the remainder into a
 // separate directive.
 func validateCredential(cred vcs.GitCredential) error {
+	// A basic credential with a secret and no username cannot authenticate.
+	// The helper would print "username=", git would read that as no
+	// username, and with prompts disabled the operation fails with "could
+	// not read Username", which says nothing about the provider that
+	// produced it. Fail here instead, where the cause is nameable.
+	if cred.Kind == vcs.CredBasic && cred.Secret != "" && cred.User == "" {
+		return fmt.Errorf("provider supplied a password with no username; git cannot authenticate with an empty username")
+	}
 	if strings.ContainsAny(cred.Secret, "\n\r") {
 		return fmt.Errorf("credential secret contains a newline, which git would read as a protocol directive")
 	}

internal/gitsync/runner_test.go

@@ -699,3 +699,33 @@ func TestPrunePRBranchesOnACacheWithNoPRBranches(t *testing.T) {
 		t.Errorf("deleted = %d, want 0", deleted)
 	}
 }
+
+func TestValidateCredentialRejectsAPasswordWithNoUsername(t *testing.T) {
+	// This is what an Azure DevOps PAT credential used to look like. The
+	// helper would print "username=", git would read that as no username,
+	// and the clone would fail with "could not read Username", which names
+	// nothing useful. Fail where the cause can be named instead.
+	err := validateCredential(vcs.GitCredential{Kind: vcs.CredBasic, Secret: "a-token"})
+	if err == nil {
+		t.Fatal("a basic credential with no username cannot authenticate and must be rejected")
+	}
+	if !strings.Contains(err.Error(), "empty username") {
+		t.Errorf("the error should name the cause, got %v", err)
+	}
+}
+
+func TestValidateCredentialAllowsNoCredentialAtAll(t *testing.T) {
+	// A local path needs no credential; that is not the same as a password
+	// with a missing username.
+	if err := validateCredential(vcs.GitCredential{}); err != nil {
+		t.Fatalf("an empty credential is valid: %v", err)
+	}
+}
+
+func TestValidateCredentialAllowsABearerWithoutAUsername(t *testing.T) {
+	// Entra mode carries the token in an Authorization header, so there is
+	// no username to supply.
+	if err := validateCredential(vcs.GitCredential{Kind: vcs.CredBearer, Secret: "entra-token"}); err != nil {
+		t.Fatalf("a bearer credential needs no username: %v", err)
+	}
+}

internal/vcs/azuredevops/azuredevops.go

@@ -141,19 +141,29 @@ func (p *Provider) CloneURL(name string) string {
 // GitCredential returns the credential git should present, matching the
 // configured auth mode.
 //
-// pat mode returns HTTP basic auth with an empty username and the PAT as
-// the password, which is what Azure DevOps expects. entra mode returns a
-// bearer credential carrying the operator supplied Entra access token. If
-// entra mode is configured but no token was ever supplied, this returns an
-// error rather than presenting an empty bearer token to git.
+// pat mode returns HTTP basic auth with the PAT as the password. Azure
+// DevOps ignores the username on this path and authenticates on the token
+// alone, so the value is free; the organisation name is used because it
+// makes the credential legible without being a secret.
+//
+// It must not be empty, which is what it used to be. SyncerD hands git its
+// credential through a helper that prints "username=<value>", and git reads
+// an empty value as no username at all: it then tries to ask, terminal
+// prompts are disabled, and the clone fails with "could not read Username"
+// rather than anything pointing at the configuration.
+//
+// entra mode returns a bearer credential carrying the operator supplied
+// Entra access token. If entra mode is configured but no token was ever
+// supplied, this returns an error rather than presenting an empty bearer
+// token to git.
 func (p *Provider) GitCredential(context.Context) (vcs.GitCredential, error) {
 	if p.auth == authEntra {
 		if p.token == "" {
 			return vcs.GitCredential{}, fmt.Errorf("azuredevops: entra mode requires a token supplied by the operator; none was configured")
 		}
 		return vcs.GitCredential{Kind: vcs.CredBearer, Secret: p.token}, nil
 	}
-	return vcs.GitCredential{Kind: vcs.CredBasic, User: "", Secret: p.token}, nil
+	return vcs.GitCredential{Kind: vcs.CredBasic, User: p.org, Secret: p.token}, nil
 }
 
 // apiRepo is the subset of the Azure DevOps repository object SyncerD

internal/vcs/azuredevops/azuredevops_test.go

@@ -311,8 +311,15 @@ func TestPATModeGitCredential(t *testing.T) {
 	if cred.Kind != vcs.CredBasic {
 		t.Errorf("Kind = %v, want CredBasic", cred.Kind)
 	}
-	if cred.User != "" {
-		t.Errorf("User = %q, want empty", cred.User)
+	// Azure DevOps ignores the username and authenticates on the PAT alone,
+	// but it cannot be empty: SyncerD's credential helper prints
+	// "username=<value>", and git reads an empty value as no username,
+	// then fails with "could not read Username" because prompts are off.
+	if cred.User == "" {
+		t.Error("User must not be empty; git cannot authenticate without one")
+	}
+	if cred.User != "acme-org" {
+		t.Errorf("User = %q, want the organisation name", cred.User)
 	}
 	if cred.Secret != "pat-test-token" {
 		t.Errorf("Secret = %q, want the PAT", cred.Secret)