patch-via-github 1.0.0__py3-none-any.whl

patch_via_github/tests/test_patch_via_github.py

@@ -0,0 +1,1576 @@
+import argparse
+import logging
+import os
+import subprocess
+import sys
+from unittest.mock import patch, MagicMock
+
+import pytest
+import requests.exceptions
+
+import patch_via_github.scripts.main as app
+from patch_via_github.tests.conftest import commit, make_pr_api_response
+
+
+def write_ini(tmp_path, *lines):
+    ini = tmp_path / "test.ini"
+    ini.write_text("\n".join(["[main]", *lines]) + "\n")
+    return str(ini)
+
+
+# ===================================================================
+# Utilities
+# ===================================================================
+
+class TestDefaultIniFile:
+    def test_under_home_ssh_dir(self, tmp_path):
+        assert app.default_ini_file() == str(
+            tmp_path / "home" / ".ssh" / "patch_via_github.ini"
+        )
+
+
+class TestParseCSVs:
+    @pytest.mark.parametrize('arguments, expected', [
+        (['value1'], ['value1']),
+        (['a,b,c'], ['a', 'b', 'c']),
+        (['a,,b'], ['a', 'b']),
+        (['a,b', 'c,d'], ['a', 'b', 'c', 'd']),
+    ])
+    def test_split(self, arguments, expected):
+        namespace = argparse.Namespace()
+        app.ParseCSVs(None, 'dest')(None, namespace, arguments, None)
+        assert namespace.dest == expected
+
+
+class TestPrKey:
+    def test_case_insensitive(self):
+        assert app.pr_key("Couchbase/TLM", "7") == "couchbase/tlm#7"
+
+    def test_number_normalised(self):
+        assert app.pr_key("couchbase/tlm", "007") == "couchbase/tlm#7"
+
+
+# ===================================================================
+# GitHubPR
+# ===================================================================
+
+class TestGitHubPR:
+    def test_init(self):
+        data = make_pr_api_response(
+            42, "tlm", head_sha="deadbeef", labels=["bug-fix", "urgent"]
+        )
+        pr = app.GitHubPR(data)
+        assert pr.number == 42
+        assert pr.project == "tlm"
+        assert pr.repo_full_name == "couchbase/tlm"
+        assert pr.branch == "master"
+        assert pr.head_sha == "deadbeef"
+        assert pr.html_url == "https://github.com/couchbase/tlm/pull/42"
+        assert pr.fetch_url == "https://github.com/couchbase/tlm.git"
+        assert pr.ref == "couchbase/tlm#42"
+        assert pr.key == "couchbase/tlm#42"
+
+    def test_commit_count(self):
+        data = make_pr_api_response(1, "tlm")
+        assert app.GitHubPR(data).commit_count is None
+        data['commits'] = 3
+        assert app.GitHubPR(data).commit_count == 3
+
+    def test_fetch_command_uses_ssh_url(self):
+        data = make_pr_api_response(7, "server-ui", org="myorg")
+        pr = app.GitHubPR(data, use_ssh=True)
+        assert pr.fetch_url == 'git@github.com:myorg/server-ui.git'
+
+
+# ===================================================================
+# GitHubPatches — Configuration
+# ===================================================================
+
+class TestGitHubPatchesConfig:
+
+    def test_from_config_file(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        assert gp.default_org == "couchbase"
+        assert gp.checkout is False
+
+    def test_missing_file_raises(self, tmp_path):
+        with pytest.raises(app.PatchError, match="nonexistent.ini missing"):
+            app.GitHubPatches.from_config_file(
+                str(tmp_path / "nonexistent.ini")
+            )
+
+    def test_unreadable_file_raises(self, tmp_path):
+        ini = write_ini(tmp_path, "token = x")
+        os.chmod(ini, 0)
+        try:
+            with pytest.raises(app.PatchError,
+                               match="Could not read configuration file"):
+                app.GitHubPatches.from_config_file(ini)
+        finally:
+            os.chmod(ini, 0o600)
+
+    def test_missing_main_section_raises(self, tmp_path):
+        bad_ini = tmp_path / "bad.ini"
+        bad_ini.write_text("[wrong]\nfoo = bar\n")
+        with pytest.raises(app.PatchError, match='missing "main" section'):
+            app.GitHubPatches.from_config_file(str(bad_ini))
+
+    @pytest.mark.parametrize('content, lines', [
+        ("[main]\nghp_SECRET\n", "2"),
+        ("ghp_SECRET\n", "1"),
+        ("[main]\ntoken = ghp_SECRET\ntoken = ghp_SECRET\n", "3"),
+    ])
+    def test_unparseable_file_does_not_quote_it(
+        self, tmp_path, content, lines
+    ):
+        ini = tmp_path / "bad.ini"
+        ini.write_text(content)
+        with pytest.raises(app.PatchError) as e:
+            app.GitHubPatches.from_config_file(str(ini))
+        assert f"could not parse line {lines})" in str(e.value)
+        assert e.value.__cause__ is None and e.value.__suppress_context__
+        assert "SECRET" not in str(e.value)
+
+    def test_missing_token_raises(self, tmp_path):
+        with pytest.raises(app.PatchError,
+                           match='Required option "token" is missing'):
+            app.GitHubPatches.from_config_file(
+                write_ini(tmp_path, "default_org = couchbase")
+            )
+
+    def test_empty_token_raises(self, tmp_path):
+        with pytest.raises(app.PatchError, match='"token" .* is empty'):
+            app.GitHubPatches.from_config_file(write_ini(tmp_path, "token ="))
+
+    def test_with_checkout(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file, checkout=True)
+        assert gp.checkout is True
+
+    def test_default_org_override(self, config_file):
+        gp = app.GitHubPatches.from_config_file(
+            config_file, default_org="other-org"
+        )
+        assert gp.default_org == "other-org"
+
+    def test_no_org_in_file(self, config_file_no_org):
+        gp = app.GitHubPatches.from_config_file(config_file_no_org)
+        assert gp.default_org is None
+
+    @staticmethod
+    def prepared_headers(gp):
+        request = requests.Request('GET', 'https://api.github.com/x')
+        return gp.session.prepare_request(request).headers
+
+    def test_request_headers(self, config_file):
+        headers = self.prepared_headers(
+            app.GitHubPatches.from_config_file(config_file)
+        )
+        assert headers['Authorization'] == (
+            'Bearer ghp_test_token_000000000000000000000'
+        )
+        assert headers['Accept'] == 'application/vnd.github+json'
+        assert headers['X-GitHub-Api-Version'] == '2022-11-28'
+
+    def test_netrc_does_not_override_token(self, tmp_path, monkeypatch):
+        netrc = tmp_path / "netrc"
+        netrc.write_text("machine api.github.com login bob password other\n")
+        monkeypatch.setenv('NETRC', str(netrc))
+        headers = self.prepared_headers(app.GitHubPatches("tok"))
+        assert headers['Authorization'] == 'Bearer tok'
+
+    def test_api_requests_retried(self):
+        retry = app.GitHubPatches("tok").session.get_adapter(
+            'https://api.github.com/x'
+        ).max_retries
+        assert retry.total == 3
+        assert {502, 503, 504, 429} <= retry.status_forcelist
+        assert retry.allowed_methods == {'GET'}
+        assert retry.raise_on_status is False
+
+    def test_ssh_default_true(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        assert gp.use_ssh is True
+
+    def test_ssh_disabled_via_config(self, tmp_path):
+        gp = app.GitHubPatches.from_config_file(
+            write_ini(tmp_path, "token = x", "ssh = false")
+        )
+        assert gp.use_ssh is False
+
+    def test_invalid_ssh_value_raises(self, tmp_path):
+        with pytest.raises(app.PatchError,
+                           match='Invalid value for "ssh".*"maybe"'):
+            app.GitHubPatches.from_config_file(
+                write_ini(tmp_path, "token = x", "ssh = maybe")
+            )
+
+
+# ===================================================================
+# GitHubPatches — PR Reference Parsing
+# ===================================================================
+
+class TestParsePrReference:
+
+    def test_full_format(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        assert gp.parse_pr_reference("myorg/myrepo#123") == (
+            "myorg", "myrepo", "123"
+        )
+
+    def test_short_format(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        assert gp.parse_pr_reference("tlm#456") == ("couchbase", "tlm", "456")
+
+    def test_short_format_no_org_raises(self, config_file_no_org):
+        gp = app.GitHubPatches.from_config_file(config_file_no_org)
+        with pytest.raises(app.PatchError, match="needs an org"):
+            gp.parse_pr_reference("tlm#456")
+
+    @pytest.mark.parametrize('ref', ["not-valid", "org/repo#", "123"])
+    def test_invalid_format_raises(self, config_file, ref):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with pytest.raises(app.PatchError) as e:
+            gp.parse_pr_reference(ref)
+        assert f'Invalid PR reference: "{ref}"' in str(e.value)
+
+
+# ===================================================================
+# GitHubPatches — API Layer
+# ===================================================================
+
+def ok_response(data, links=None):
+    response = MagicMock()
+    response.json.return_value = data
+    response.links = links or {}
+    response.raise_for_status.return_value = None
+    return response
+
+
+def api_response(status, reason, body=b'not json', headers=None,
+                 url='https://api.github.com/x'):
+    response = requests.models.Response()
+    response.status_code = status
+    response.reason = reason
+    response.url = url
+    response.headers.update(headers or {})
+    response._content = body
+    return response
+
+
+def http_error_response(status, reason, message=None, headers=None):
+    body = f'{{"message": "{message}"}}'.encode() if message else b'{}'
+    return api_response(status, reason, body, headers)
+
+
+class TestApiRequests:
+
+    def test_get_returns_json_from_full_url(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp.session, 'get',
+                          return_value=ok_response({"id": 1})) as mock_get:
+            result = gp._api_get('/repos/org/repo/pulls/42')
+        assert result == {"id": 1}
+        mock_get.assert_called_once_with(
+            'https://api.github.com/repos/org/repo/pulls/42', timeout=30
+        )
+
+    def test_http_error_without_response(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        response = MagicMock()
+        response.raise_for_status.side_effect = (
+            requests.exceptions.HTTPError("404 Not Found")
+        )
+        with patch.object(gp.session, 'get', return_value=response):
+            with pytest.raises(app.PatchError,
+                               match="^GitHub API error: 404 Not Found$"):
+                gp._api_get('/x')
+
+    def test_connection_error(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp.session, 'get',
+                          side_effect=requests.exceptions.ConnectionError(
+                              "Name or service not known")):
+            with pytest.raises(app.PatchError,
+                               match="Name or service not known"):
+                gp._api_get('/x')
+
+    def test_timeout(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp.session, 'get',
+                          side_effect=requests.exceptions.Timeout("slow")):
+            with pytest.raises(app.PatchError, match="slow"):
+                gp._api_get_paginated('/x')
+
+    def test_invalid_json(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        response = api_response(200, 'OK')
+        with patch.object(gp.session, 'get', return_value=response):
+            with pytest.raises(app.PatchError, match="invalid JSON"):
+                gp._api_get('/x')
+
+    @pytest.mark.parametrize('status, reason, message, headers, expected', [
+        (401, 'Unauthorized', 'Bad credentials', {},
+         "401 Unauthorized for https://api.github.com/x (Bad credentials)"
+         " - check the token"),
+        (404, 'Not Found', 'Not Found', {}, "can access the repository"),
+        (403, 'Forbidden', 'Resource protected by SAML', {},
+         "(Resource protected by SAML) - check your token has access"),
+        (403, 'Forbidden', 'API rate limit exceeded',
+         {'X-RateLimit-Remaining': '0', 'X-RateLimit-Reset': '0'},
+         "rate limit exhausted, resets at "),
+        (403, 'Forbidden', 'API rate limit exceeded',
+         {'X-RateLimit-Remaining': '0', 'X-RateLimit-Reset': 'soon'},
+         "rate limit exhausted, X-RateLimit-Reset: soon"),
+        (403, 'Forbidden', 'secondary rate limit', {'Retry-After': '60'},
+         "secondary rate limit hit, retry after 60 seconds"),
+        (500, 'Server Error', None, {},
+         "GitHub API error: 500 Server Error for https://api.github.com/x"),
+    ])
+    def test_http_error_message(
+        self, config_file, status, reason, message, headers, expected
+    ):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        response = http_error_response(status, reason, message, headers)
+        with patch.object(gp.session, 'get', return_value=response):
+            with pytest.raises(app.PatchError) as e:
+                gp._api_get('/x')
+        assert expected in str(e.value)
+
+    def test_rate_limit_without_reset_header(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        response = http_error_response(
+            403, 'Forbidden', 'API rate limit exceeded',
+            {'X-RateLimit-Remaining': '0'}
+        )
+        with patch.object(gp.session, 'get', return_value=response):
+            with pytest.raises(app.PatchError) as e:
+                gp._api_get('/x')
+        assert str(e.value).endswith("rate limit exhausted")
+
+    def test_non_json_error_body(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        response = api_response(502, 'Bad Gateway', b'<html>oops</html>')
+        with patch.object(gp.session, 'get', return_value=response):
+            with pytest.raises(app.PatchError) as e:
+                gp._api_get('/x')
+        assert str(e.value) == (
+            "GitHub API error: 502 Bad Gateway for https://api.github.com/x"
+        )
+
+    def test_paginated_follows_link_header(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        page1 = api_response(200, 'OK', b'[{"id": 1}, {"id": 2}]', {
+            'Link': '<https://api.github.com/p2>; rel="next", '
+                    '<https://api.github.com/p2>; rel="last"'
+        })
+        page2 = api_response(200, 'OK', b'[{"id": 3}]')
+        with patch.object(gp.session, 'get',
+                          side_effect=[page1, page2]) as mock_get:
+            results = gp._api_get_paginated('/endpoint')
+        assert results == [{"id": 1}, {"id": 2}, {"id": 3}]
+        assert [c.args[0] for c in mock_get.call_args_list] == [
+            "https://api.github.com/endpoint", "https://api.github.com/p2"
+        ]
+
+    @pytest.mark.parametrize('next_url', [
+        "https://evil.example/p2", "https://api.github.com.evil.example/p2",
+        "http://api.github.com/p2",
+    ])
+    def test_paginated_refuses_off_host_link(self, config_file, next_url):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        page1 = ok_response([{"id": 1}], {"next": {"url": next_url}})
+        with patch.object(gp.session, 'get',
+                          side_effect=[page1, ok_response([])]) as mock_get:
+            with pytest.raises(app.PatchError, match="refusing to follow"):
+                gp._api_get_paginated('/endpoint')
+        mock_get.assert_called_once()
+
+    def test_paginated_non_list_response(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp.session, 'get',
+                          return_value=ok_response({"message": "odd"})):
+            with pytest.raises(app.PatchError, match="expected a list"):
+                gp._api_get_paginated('/x')
+
+    def test_malformed_pr_data(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp, '_api_get', return_value={"number": 1}):
+            with pytest.raises(app.PatchError, match="unexpected PR data"):
+                gp.get_pr("couchbase", "tlm", "1")
+
+    def test_malformed_pr_listing(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp, '_api_get_paginated',
+                          return_value=[{"number": 1}]):
+            with pytest.raises(app.PatchError, match="unexpected PR data"):
+                gp.get_open_prs_by_label("couchbase", "tlm", "x")
+
+
+class TestGetPr:
+
+    def test_fetches_pr_from_endpoint(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch.object(gp, '_api_get',
+                          return_value=make_pr_api_response(42, "myrepo")
+                          ) as mock_api:
+            pr = gp.get_pr("myorg", "myrepo", "42")
+        mock_api.assert_called_once_with('/repos/myorg/myrepo/pulls/42')
+        assert pr.key == "couchbase/myrepo#42"
+
+
+class TestGetOpenPrsByLabel:
+
+    def test_filters_open_prs_by_label(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        listing = [
+            make_pr_api_response(1, "tlm", labels=["backport"]),
+            make_pr_api_response(2, "tlm", labels=["feature"]),
+            make_pr_api_response(3, "tlm", labels=["backport", "urgent"]),
+        ]
+        with patch.object(gp, '_api_get_paginated',
+                          return_value=listing) as mock_api:
+            prs = gp.get_open_prs_by_label("couchbase", "tlm", "backport")
+        mock_api.assert_called_once_with(
+            '/repos/couchbase/tlm/pulls?state=open&per_page=100'
+        )
+        assert sorted(prs) == ["couchbase/tlm#1", "couchbase/tlm#3"]
+
+    @pytest.mark.parametrize('use_ssh, url_field', [
+        (True, 'ssh_url'), (False, 'clone_url'),
+    ])
+    def test_fetch_url_follows_ssh_setting(
+        self, config_file, use_ssh, url_field
+    ):
+        gp = app.GitHubPatches.from_config_file(config_file, use_ssh=use_ssh)
+        data = make_pr_api_response(1, "tlm", labels=["x"])
+        with patch.object(gp, '_api_get_paginated', return_value=[data]):
+            pr, = gp.get_open_prs_by_label("couchbase", "tlm", "x").values()
+        assert pr.fetch_url == data['base']['repo'][url_field]
+
+
+# ===================================================================
+# Manifest Resolution
+# ===================================================================
+
+class TestManifestResolution:
+
+    @pytest.mark.parametrize('project, expected', [
+        ("server-ui", ("server-ui", "main")),
+        ("couchbase-cli", ("couchbase-cli-tools", "master")),
+        ("cbgt", ("cbgt", "master")),  # inherits <default revision>
+        ("stellar-gateway",
+         ("stellar-gateway", "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2")),
+        ("eventing",
+         ("goproj/src/github.com/couchbase/eventing", "master")),
+        ("tlm", ("tlm", "master")),
+        ("ns_server", ("ns_server", "master")),
+        ("build", ("build", "master")),
+        ("geocouch",
+         ("geocouch", "3e8040787139e3c67766ce50398860c185737b8a")),
+        ("nonexistent", (None, None)),
+    ])
+    def test_lookup(self, gp_with_manifest, project, expected):
+        assert gp_with_manifest.get_project_path_and_branch_from_manifest(
+            project
+        ) == expected
+
+    @pytest.mark.parametrize('project, branch', [
+        ("own", "own-rev"),
+        ("via-remote", "remote-rev"),
+        ("other-remote", "default-rev"),
+        ("full-ref", "trinity"),
+        ("tag", "refs/tags/v1"),
+    ])
+    def test_revision_precedence(self, config_file, project, branch):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        gp.manifest = app.EleTree.fromstring(
+            '<manifest>'
+            '<remote name="r" revision="remote-rev"/><remote name="s"/>'
+            '<default remote="r" revision="default-rev"/>'
+            '<project name="own" revision="own-rev"/>'
+            '<project name="via-remote"/>'
+            '<project name="other-remote" remote="s"/>'
+            '<project name="full-ref" revision="refs/heads/trinity"/>'
+            '<project name="tag" revision="refs/tags/v1"/>'
+            '</manifest>'
+        )
+        assert gp.get_project_path_and_branch_from_manifest(project) == (
+            project, branch
+        )
+
+    def test_no_revision_anywhere(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        gp.manifest = app.EleTree.fromstring(
+            '<manifest><project name="p"/></manifest>'
+        )
+        assert gp.get_project_path_and_branch_from_manifest("p") == (
+            "p", None
+        )
+
+    def test_stale_manifest_read_from_repo_tool(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        manifest_xml = (
+            b'<manifest>'
+            b'<default revision="main"/>'
+            b'<project name="foo" revision="dev"/>'
+            b'</manifest>'
+        )
+        with patch('patch_via_github.scripts.main.which',
+                   return_value='/usr/bin/repo'), \
+             patch('subprocess.check_output',
+                   return_value=manifest_xml) as mock_run:
+            assert gp.get_project_path_and_branch_from_manifest("foo") == (
+                "foo", "dev"
+            )
+            gp.get_project_path_and_branch_from_manifest("foo")
+        mock_run.assert_called_once_with(
+            ['/usr/bin/repo', 'manifest'], timeout=app.REPO_MANIFEST_TIMEOUT
+        )
+
+    def test_missing_repo_tool_raises(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch('patch_via_github.scripts.main.which', return_value=None):
+            with pytest.raises(app.PatchError, match="'repo' tool"):
+                gp.get_project_path_and_branch_from_manifest("foo")
+
+    def test_repo_tool_not_runnable_raises(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch('patch_via_github.scripts.main.which',
+                   return_value='/nonexistent/repo'):
+            with pytest.raises(app.PatchError,
+                               match="Could not run 'repo manifest'"):
+                gp.get_project_path_and_branch_from_manifest("foo")
+
+    def test_repo_manifest_failure_raises(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch('patch_via_github.scripts.main.which',
+                   return_value='/usr/bin/repo'), \
+             patch('subprocess.check_output',
+                   side_effect=subprocess.CalledProcessError(1, 'repo')):
+            with pytest.raises(app.PatchError, match="repo manifest"):
+                gp.get_project_path_and_branch_from_manifest("foo")
+
+    @pytest.mark.parametrize('outcome, expected', [
+        ({'return_value': b'<manifest'}, "Could not parse 'repo manifest'"),
+        ({'side_effect': subprocess.TimeoutExpired('repo', 300)},
+         "'repo manifest' timed out after 300s"),
+    ])
+    def test_repo_manifest_bad_output_or_timeout_raises(
+        self, config_file, outcome, expected
+    ):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        with patch('patch_via_github.scripts.main.which',
+                   return_value='/usr/bin/repo'), \
+             patch('subprocess.check_output', **outcome):
+            with pytest.raises(app.PatchError, match=expected):
+                gp.get_project_path_and_branch_from_manifest("foo")
+
+
+# ===================================================================
+# resolve_prs — PR Orchestration & Branch Filtering
+# ===================================================================
+
+class TestResolvePrsByPr:
+
+    def test_pr_not_found_raises(self, gp_with_manifest):
+        gp = gp_with_manifest
+        with patch.object(
+            gp, '_api_get',
+            side_effect=app.PatchError("GitHub API error: 404")
+        ):
+            with pytest.raises(
+                app.PatchError,
+                match="Failed to fetch couchbase/server-ui#999: "
+                      "GitHub API error: 404"
+            ):
+                gp.resolve_prs(["couchbase/server-ui#999"], 'pr')
+
+    def test_every_ref_validated_before_fetching(self, gp_with_manifest):
+        gp = gp_with_manifest
+        with patch.object(gp, '_api_get') as mock_api:
+            with pytest.raises(app.PatchError, match="Invalid PR reference"):
+                gp.resolve_prs(["couchbase/server-ui#1", "bad"], 'pr')
+        mock_api.assert_not_called()
+
+    def test_open_pr_matching_branch_included(self, gp_with_manifest):
+        gp = gp_with_manifest
+        pr_data = make_pr_api_response(10, "server-ui", base_ref="main")
+        with patch.object(gp, '_api_get', return_value=pr_data):
+            prs = gp.resolve_prs(["couchbase/server-ui#10"], 'pr')
+        assert list(prs) == ["couchbase/server-ui#10"]
+
+    @pytest.mark.parametrize('state, base_ref', [
+        ("closed", "main"), ("open", "develop"),
+    ])
+    def test_requested_pr_kept_whatever_state_or_branch(
+        self, gp_with_manifest, state, base_ref
+    ):
+        gp = gp_with_manifest
+        pr_data = make_pr_api_response(
+            10, "server-ui", base_ref=base_ref, state=state
+        )
+        with patch.object(gp, '_api_get', return_value=pr_data):
+            prs = gp.resolve_prs(["couchbase/server-ui#10"], 'pr')
+        assert list(prs) == ["couchbase/server-ui#10"]
+
+    def test_same_number_in_different_repos_both_kept(
+        self, gp_with_manifest
+    ):
+        gp = gp_with_manifest
+        pr1 = make_pr_api_response(10, "server-ui", base_ref="main")
+        pr2 = make_pr_api_response(10, "couchbase-cli", base_ref="master")
+
+        def mock_api_get(endpoint):
+            return pr1 if "server-ui" in endpoint else pr2
+
+        with patch.object(gp, '_api_get', side_effect=mock_api_get):
+            prs = gp.resolve_prs(
+                ["couchbase/server-ui#10", "couchbase/couchbase-cli#10"],
+                'pr'
+            )
+        assert set(prs) == {
+            "couchbase/server-ui#10", "couchbase/couchbase-cli#10"
+        }
+
+    def test_request_order_kept_duplicates_at_first_position(
+        self, gp_with_manifest
+    ):
+        gp = gp_with_manifest
+
+        def api_get(endpoint):
+            repo, number = endpoint.split('/')[3], endpoint.split('/')[-1]
+            return make_pr_api_response(int(number), repo)
+
+        with patch.object(gp, '_api_get', side_effect=api_get):
+            prs = gp.resolve_prs([
+                "couchbase/tlm#30", "couchbase/server-ui#2",
+                "couchbase/tlm#4", "couchbase/server-ui#2",
+            ], 'pr')
+        assert list(prs) == [
+            "couchbase/tlm#30", "couchbase/server-ui#2", "couchbase/tlm#4"
+        ]
+
+    def test_renamed_repo_keyed_by_canonical_name(self, gp_with_manifest):
+        gp = gp_with_manifest
+        pr_data = make_pr_api_response(10, "server-ui", base_ref="main")
+        with patch.object(gp, '_api_get', return_value=pr_data):
+            prs = gp.resolve_prs(
+                ["couchbase/old-name#10", "couchbase/server-ui#10"], 'pr'
+            )
+        assert list(prs) == ["couchbase/server-ui#10"]
+
+
+class TestResolvePrsByLabel:
+
+    def test_valid_label_returns_matching_prs(self, gp_with_manifest):
+        gp = gp_with_manifest
+        listing = [
+            make_pr_api_response(
+                1, "server-ui", base_ref="main", labels=["backport"]
+            ),
+            make_pr_api_response(
+                2, "server-ui", base_ref="main", labels=["feature"]
+            ),
+        ]
+        with patch.object(gp, '_api_get_paginated', return_value=listing):
+            prs = gp.resolve_prs(["couchbase/server-ui:backport"], 'label')
+        assert list(prs) == ["couchbase/server-ui#1"]
+
+    def test_label_order_then_pr_number_order(self, gp_with_manifest):
+        gp = gp_with_manifest
+        listings = {
+            "server-ui": [make_pr_api_response(n, "server-ui", base_ref="main",
+                                               labels=["x"])
+                          for n in (30, 4, 12)],
+            "couchbase-cli": [make_pr_api_response(n, "couchbase-cli",
+                                                   labels=["x"])
+                              for n in (7, 1)],
+        }
+        with patch.object(gp, '_api_get_paginated',
+                          side_effect=lambda e: listings[e.split('/')[3]]):
+            prs = gp.resolve_prs(
+                ["couchbase/server-ui:x", "couchbase/couchbase-cli:x",
+                 "couchbase/server-ui:x"], 'label'
+            )
+        assert list(prs) == [
+            "couchbase/server-ui#4", "couchbase/server-ui#12",
+            "couchbase/server-ui#30", "couchbase/couchbase-cli#1",
+            "couchbase/couchbase-cli#7",
+        ]
+
+    def test_invalid_label_format_raises(self, gp_with_manifest):
+        gp = gp_with_manifest
+        with patch.object(gp, '_api_get_paginated') as mock_api:
+            with pytest.raises(
+                app.PatchError,
+                match='Invalid label reference: "invalid-label-format"'
+            ):
+                gp.resolve_prs(
+                    ["couchbase/server-ui:ok", "invalid-label-format"],
+                    'label'
+                )
+        mock_api.assert_not_called()
+
+    def test_same_number_in_different_repos_both_kept(
+        self, gp_with_manifest
+    ):
+        gp = gp_with_manifest
+
+        def mock_paginated(endpoint):
+            repo = "server-ui" if "server-ui" in endpoint else "couchbase-cli"
+            branch = "main" if repo == "server-ui" else "master"
+            return [make_pr_api_response(
+                5, repo, base_ref=branch, labels=["backport"]
+            )]
+
+        with patch.object(gp, '_api_get_paginated',
+                          side_effect=mock_paginated):
+            prs = gp.resolve_prs([
+                "couchbase/server-ui:backport",
+                "couchbase/couchbase-cli:backport",
+            ], 'label')
+        assert set(prs) == {
+            "couchbase/server-ui#5", "couchbase/couchbase-cli#5"
+        }
+
+    def test_api_error_raises(self, gp_with_manifest):
+        gp = gp_with_manifest
+        with patch.object(gp, '_api_get_paginated',
+                          side_effect=app.PatchError("boom")):
+            with pytest.raises(
+                app.PatchError,
+                match="Failed to fetch PRs for couchbase/server-ui:backport: "
+                      "boom"
+            ):
+                gp.resolve_prs(["couchbase/server-ui:backport"], 'label')
+
+    def test_label_branch_mismatch_filtered(self, gp_with_manifest):
+        gp = gp_with_manifest
+        listing = [make_pr_api_response(
+            1, "server-ui", base_ref="develop", labels=["backport"]
+        )]
+        with patch.object(gp, '_api_get_paginated', return_value=listing):
+            prs = gp.resolve_prs(["couchbase/server-ui:backport"], 'label')
+        assert prs == {}
+
+    def test_sha_locked_manifest_skips_branch_filter(self, gp_with_manifest):
+        gp = gp_with_manifest
+        listing = [make_pr_api_response(
+            70, "stellar-gateway", base_ref="feature-x", labels=["x"]
+        )]
+        with patch.object(gp, '_api_get_paginated', return_value=listing):
+            prs = gp.resolve_prs(["couchbase/stellar-gateway:x"], 'label')
+        assert list(prs) == ["couchbase/stellar-gateway#70"]
+
+    def test_project_not_in_manifest_kept(self, gp_with_manifest):
+        gp = gp_with_manifest
+        listing = [make_pr_api_response(
+            1, "nonexistent-repo", base_ref="develop", labels=["backport"]
+        )]
+        with patch.object(gp, '_api_get_paginated', return_value=listing):
+            prs = gp.resolve_prs(
+                ["couchbase/nonexistent-repo:backport"], 'label'
+            )
+        assert list(prs) == ["couchbase/nonexistent-repo#1"]
+
+
+# ===================================================================
+# check_requested_prs_applied
+# ===================================================================
+
+class TestCheckRequestedPrsApplied:
+
+    @pytest.fixture(autouse=True)
+    def info_logs(self, caplog):
+        caplog.set_level(logging.INFO, logger='patch_via_github')
+
+    @pytest.fixture
+    def gp(self, config_file):
+        return app.GitHubPatches.from_config_file(config_file)
+
+    def test_all_applied_succeeds(self, gp, caplog):
+        gp.applied_prs = ["couchbase/tlm#42"]
+        gp.check_requested_prs_applied('pr', [], ["couchbase/tlm#42"])
+        assert "All explicitly-requested PRs applied" in caplog.text
+
+    def test_missing_pr_raises(self, gp):
+        with pytest.raises(
+            app.PatchError,
+            match=r"Failed to apply all explicitly-requested PRs! "
+                  r"Requested: \['couchbase/tlm#42'\] Applied: \[\]"
+        ):
+            gp.check_requested_prs_applied('pr', [], ["couchbase/tlm#42"])
+
+    def test_same_number_other_repo_does_not_count(self, gp):
+        gp.applied_prs = ["couchbase/kv_engine#123"]
+        with pytest.raises(app.PatchError):
+            gp.check_requested_prs_applied('pr', [], [
+                "couchbase/kv_engine#123", "couchbase/ns_server#123"
+            ])
+
+    def test_nothing_requested_or_applied_is_silent(self, gp, caplog):
+        gp.check_requested_prs_applied('pr', [], [])
+        assert caplog.text == ""
+
+    def test_label_mode_reporting(self, gp, caplog):
+        gp.applied_prs = ["couchbase/tlm#10", "couchbase/tlm#20"]
+        gp.check_requested_prs_applied(
+            'label', ["couchbase/tlm:backport"], ["couchbase/tlm#30"]
+        )
+        assert (
+            "Applied PRs from label(s) 'couchbase/tlm:backport': "
+            "['couchbase/tlm#10', 'couchbase/tlm#20']"
+        ) in caplog.text
+
+    def test_label_mode_nothing_applied_is_silent(self, gp, caplog):
+        gp.check_requested_prs_applied('label', ["couchbase/tlm:x"], [])
+        assert caplog.text == ""
+
+
+# ===================================================================
+# load_pr_commits
+# ===================================================================
+
+class TestLoadPrCommits:
+
+    @staticmethod
+    def pr(head_sha, commit_count):
+        data = make_pr_api_response(1, "tlm", head_sha=head_sha)
+        data['commits'] = commit_count
+        return app.GitHubPR(data)
+
+    def test_linear_history_oldest_first(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c3", 3)
+        data = [commit("c1", ["base"]), commit("c2", ["c1"]),
+                commit("c3", ["c2"])]
+        with patch.object(gp, '_api_get_paginated',
+                          return_value=data) as mock_api:
+            gp.load_pr_commits(pr)
+        assert pr.commits == ["c1", "c2", "c3"]
+        mock_api.assert_called_once_with(
+            '/repos/couchbase/tlm/pulls/1/commits?per_page=100'
+        )
+
+    def test_order_of_api_listing_does_not_matter(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c3", 3)
+        data = [commit("c2", ["c1"]), commit("c3", ["c2"]),
+                commit("c1", ["base"])]
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            gp.load_pr_commits(pr)
+        assert pr.commits == ["c1", "c2", "c3"]
+
+    def test_merge_commit_rejected(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c2", 2)
+        data = [commit("c1", ["base"]), commit("c2", ["c1", "other"])]
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            with pytest.raises(app.PatchError, match="merge commit"):
+                gp.load_pr_commits(pr)
+
+    def test_commit_outside_head_ancestry_rejected(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c2", 3)
+        data = [commit("c1", ["base"]), commit("c2", ["c1"]),
+                commit("stray", ["base"])]
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            with pytest.raises(app.PatchError, match="stray"):
+                gp.load_pr_commits(pr)
+
+    def test_head_missing_from_listing_rejected(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c9", 2)
+        data = [commit("c1", ["base"]), commit("c2", ["c1"])]
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            with pytest.raises(app.PatchError, match="not in the commit"):
+                gp.load_pr_commits(pr)
+
+    def test_count_mismatch_rejected(self, config_file):
+        """A truncated listing that still ends at head must not pass."""
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c3", 5)
+        data = [commit("c2", ["c1"]), commit("c3", ["c2"])]
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            with pytest.raises(app.PatchError, match="reports 5 commits"):
+                gp.load_pr_commits(pr)
+
+    def test_250_commits_accepted(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        shas = [f"c{i}" for i in range(1, 251)]
+        data = [commit(sha, [parent])
+                for sha, parent in zip(shas, ["base", *shas])]
+        pr = self.pr("c250", 250)
+        with patch.object(gp, '_api_get_paginated', return_value=data):
+            gp.load_pr_commits(pr)
+        assert pr.commits == shas
+
+    def test_over_250_commits_rejected_without_listing(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c251", 251)
+        with patch.object(gp, '_api_get_paginated') as mock_api:
+            with pytest.raises(app.PatchError, match="251 commits"):
+                gp.load_pr_commits(pr)
+        mock_api.assert_not_called()
+
+    def test_missing_count_fetched_from_single_pr(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c1", None)
+        latest = self.pr("c1", 1)
+        with patch.object(gp, 'get_pr', return_value=latest) as mock_get, \
+             patch.object(gp, '_api_get_paginated',
+                          return_value=[commit("c1", ["base"])]):
+            gp.load_pr_commits(pr)
+        mock_get.assert_called_once_with("couchbase", "tlm", 1)
+        assert pr.commits == ["c1"]
+
+    def test_count_missing_from_single_pr_raises(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c1", None)
+        with patch.object(gp, 'get_pr', return_value=self.pr("c1", None)):
+            with pytest.raises(app.PatchError, match="no commit count"):
+                gp.load_pr_commits(pr)
+
+    def test_head_moved_while_fetching_count(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c1", None)
+        with patch.object(gp, 'get_pr', return_value=self.pr("c2", 2)):
+            with pytest.raises(app.PatchError, match="head moved"):
+                gp.load_pr_commits(pr)
+
+    def test_malformed_commit_data(self, config_file):
+        gp = app.GitHubPatches.from_config_file(config_file)
+        pr = self.pr("c1", 1)
+        with patch.object(gp, '_api_get_paginated',
+                          return_value=[{"sha": "c1"}]):
+            with pytest.raises(app.PatchError, match="unexpected commit"):
+                gp.load_pr_commits(pr)
+
+
+# ===================================================================
+# apply_single_pr — against real git repositories
+# ===================================================================
+
+def apply(gp, pr, api_commits, path):
+    with patch.object(gp, '_api_get_paginated', return_value=api_commits):
+        gp.apply_single_pr(pr, str(path))
+
+
+class TestApplySinglePr:
+
+    @pytest.fixture(autouse=True)
+    def info_logs(self, caplog):
+        caplog.set_level(logging.INFO, logger='patch_via_github')
+
+    @pytest.fixture
+    def gp(self, config_file):
+        return app.GitHubPatches.from_config_file(config_file, use_ssh=False)
+
+    def test_missing_dir_raises_exit_5(self, gp):
+        pr = app.GitHubPR(make_pr_api_response(1, "tlm"))
+        with pytest.raises(app.PatchError, match="missing on disk") as e:
+            gp.apply_single_pr(pr, "/nonexistent_path_xyz")
+        assert e.value.exit_code == 5
+
+    def test_dir_not_a_git_checkout_raises(self, gp, tmp_path, monkeypatch):
+        monkeypatch.setenv('GIT_CEILING_DIRECTORIES', str(tmp_path))
+        (tmp_path / "plain").mkdir()
+        pr = app.GitHubPR(make_pr_api_response(1, "tlm"))
+        with pytest.raises(app.PatchError, match="not a usable git checkout"):
+            gp.apply_single_pr(pr, str(tmp_path / "plain"))
+        assert gp.originals == {}
+
+    def test_cherry_picks_every_pr_commit(self, gp, repos, caplog):
+        pr, api_commits = repos.make_pr(1, "p1", [
+            ("f", "base\none\n", "c1"),
+            ("f", "base\none\ntwo\n", "c2"),
+            ("g", "new\n", "c3"),
+        ])
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["c3", "c2", "c1", "base"]
+        assert repos.work_file("f") == "base\none\ntwo\n"
+        assert gp.applied_prs == ["couchbase/work#1"]
+        assert "Cherry-picked 3 of 3 commit(s)" in caplog.text
+        assert "added no new changes" not in caplog.text
+
+    def test_lands_on_top_of_local_commits(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "x\n", "c1")])
+        repos.commit_file("h", "local\n", "local", repo=repos.work)
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["c1", "local", "base"]
+
+    def test_stacked_pr_skips_commits_already_applied(
+        self, gp, repos, caplog
+    ):
+        pr1, commits1 = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("h", "two\n", "c1b"),
+        ])
+        pr2, commits2 = repos.make_pr(2, "p2", [
+            ("i", "three\n", "c2"),
+        ], start="p1")
+        # A stacked PR on GitHub lists its dependency's commits too
+        pr2.commit_count = 3
+        apply(gp, pr1, commits1, repos.work)
+        caplog.clear()
+        apply(gp, pr2, commits1 + commits2, repos.work)
+        assert repos.work_log() == ["c2", "c1b", "c1", "base"]
+        assert "Skipped the first 2 commit(s)" in caplog.text
+        assert "Cherry-picked 1 of 3 commit(s)" in caplog.text
+        assert gp.applied_prs == ["couchbase/work#1", "couchbase/work#2"]
+
+    def test_squash_merged_dependency_skipped(self, gp, repos):
+        pr1, commits1 = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("g", "one\ntwo\n", "c1b"),
+        ])
+        pr2, commits2 = repos.make_pr(2, "p2", [
+            ("h", "three\n", "c2"),
+        ], start="p1")
+        pr2.commit_count = 3
+        repos.commit_file("g", "one\ntwo\n", "squashed", repo=repos.work)
+        apply(gp, pr2, commits1 + commits2, repos.work)
+        assert repos.work_log() == ["c2", "squashed", "base"]
+
+    def test_commit_already_present_mid_pr_skipped(self, gp, repos, caplog):
+        pr, api_commits = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("h", "two\n", "c2"),
+        ])
+        repos.commit_file("h", "two\n", "local h", repo=repos.work)
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["c1", "local h", "base"]
+        assert (f"Skipped commit {api_commits[0]['sha']}: its changes are "
+                "already present") in caplog.text
+        assert "Cherry-picked 1 of 2 commit(s)" in caplog.text
+        assert "added no new changes" not in caplog.text
+
+    def test_fully_present_pr_warns(self, gp, repos, caplog):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        repos.commit_file("g", "one\n", "same change", repo=repos.work)
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["same change", "base"]
+        assert "couchbase/work#1 added no new changes" in caplog.text
+        assert gp.applied_prs == ["couchbase/work#1"]
+
+    def test_commit_already_present_with_unrelated_local_edits(
+        self, gp, repos, caplog
+    ):
+        pr, api_commits = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("h", "two\n", "c2"),
+        ])
+        repos.commit_file("h", "two\n", "local h", repo=repos.work)
+        (repos.work / "f").write_text("base\nlocal edit\n")
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["c1", "local h", "base"]
+        assert "its changes are already present" in caplog.text
+        assert repos.work_file("f") == "base\nlocal edit\n"
+
+    def test_empty_commit_in_pr_skipped(self, gp, repos, caplog):
+        pr, api_commits = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("g", None, "empty"),
+            ("h", "two\n", "c2"),
+        ])
+        apply(gp, pr, api_commits, repos.work)
+        assert repos.work_log() == ["c2", "c1", "base"]
+        assert "it is empty in the PR" in caplog.text
+        assert "Cherry-picked 2 of 3 commit(s)" in caplog.text
+
+    def test_conflict_is_informative(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("f", "theirs\n", "c1")])
+        repos.commit_file("f", "ours\n", "local", repo=repos.work)
+        with pytest.raises(app.PatchError) as e:
+            apply(gp, pr, api_commits, repos.work)
+        msg = str(e.value)
+        assert f"git cherry-pick {api_commits[0]['sha']}" in msg
+        assert "couchbase/work#1" in msg
+        assert "CONFLICT" in msg
+        assert "cherry-pick --abort" in msg
+        assert gp.applied_prs == []
+
+    @pytest.mark.parametrize('checkout', [False, True])
+    def test_fetched_head_mismatch_raises(self, config_file, repos, checkout):
+        gp = app.GitHubPatches.from_config_file(
+            config_file, checkout=checkout, use_ssh=False
+        )
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        before = repos.git(repos.work, 'rev-parse', 'HEAD')
+        # PR force-pushed after GitHub told us its head
+        repos.make_pr(1, "p1", [("g", "other\n", "c1'")])
+        with pytest.raises(app.PatchError, match="updated during"):
+            apply(gp, pr, api_commits, repos.work)
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == before
+
+    def test_fetch_failure_is_informative(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        pr.fetch_url = str(repos.root / "no-such-repo")
+        with pytest.raises(app.PatchError) as e:
+            apply(gp, pr, api_commits, repos.work)
+        assert f"git fetch {pr.fetch_url} pull/1/head" in str(e.value)
+        assert "cherry-pick --abort" not in str(e.value)
+
+    def test_fetch_timeout_raises(self, gp, repos, monkeypatch):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        real_run = subprocess.run
+
+        def run(command, **kwargs):
+            if command[1] == 'fetch':
+                assert kwargs['timeout'] == app.FETCH_TIMEOUT
+                raise subprocess.TimeoutExpired(command, kwargs['timeout'])
+            return real_run(command, **kwargs)
+
+        monkeypatch.setattr(subprocess, 'run', run)
+        with pytest.raises(app.PatchError,
+                           match=f"timed out after {app.FETCH_TIMEOUT}s"):
+            apply(gp, pr, api_commits, repos.work)
+
+    def test_git_not_runnable_raises(self, gp, repos, monkeypatch):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        monkeypatch.setenv('PATH', '')
+        with pytest.raises(app.PatchError, match="Could not run git"):
+            apply(gp, pr, api_commits, repos.work)
+
+    def test_present_prefix_diff_failure_raises(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        pr.commits = ["0" * 40]
+        with pytest.raises(app.PatchError, match="git diff --binary"):
+            gp._present_prefix(pr, str(repos.work))
+
+    def test_checkout_mode(self, config_file, repos):
+        gp = app.GitHubPatches.from_config_file(
+            config_file, checkout=True, use_ssh=False
+        )
+        pr, _ = repos.make_pr(1, "p1", [
+            ("g", "one\n", "c1"), ("g", "two\n", "c2"),
+        ])
+        with patch.object(gp, 'load_pr_commits') as mock_load:
+            gp.apply_single_pr(pr, str(repos.work))
+        mock_load.assert_not_called()
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == pr.head_sha
+
+
+
+class TestRollBack:
+
+    @pytest.fixture
+    def gp(self, config_file):
+        return app.GitHubPatches.from_config_file(config_file, use_ssh=False)
+
+    def test_failure_rolls_back_every_touched_project(
+        self, gp, repos, caplog, monkeypatch
+    ):
+        other = repos.clone(repos.root / "other")
+        before_work = repos.git(repos.work, 'rev-parse', 'HEAD')
+        pr1, _ = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        pr2, _ = repos.make_pr(2, "p2", [("f", "theirs\n", "c2")],
+                               project="other")
+        repos.commit_file("f", "ours\n", "local", repo=other)
+        before_other = repos.git(other, 'rev-parse', 'HEAD')
+
+        gp.manifest = app.EleTree.fromstring(
+            '<manifest><project name="work"/><project name="other"/>'
+            '</manifest>'
+        )
+        monkeypatch.chdir(repos.root)
+        with patch.object(gp, 'resolve_prs',
+                          return_value={pr1.key: pr1, pr2.key: pr2}), \
+             patch.object(gp, '_api_get_paginated',
+                          side_effect=repos.api_get):
+            with pytest.raises(SystemExit) as e:
+                gp.patch_repo_sync([], 'pr')
+
+        assert e.value.code == 5
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == before_work
+        assert repos.git(repos.work, 'symbolic-ref', '--short',
+                         'HEAD') == 'master'
+        assert repos.git(other, 'rev-parse', 'HEAD') == before_other
+        assert repos.git(other, 'status', '--porcelain') == ''
+        assert "PRs applied: couchbase/work#1)" in caplog.text
+        assert "Rolled back work to master at" in caplog.text
+        assert "Rolled back other to master at" in caplog.text
+
+    def test_project_patched_twice_restored_to_first_original(
+        self, gp, repos
+    ):
+        before = repos.git(repos.work, 'rev-parse', 'HEAD')
+        pr1, commits1 = repos.make_pr(1, "p1", [("f", "one\n", "c1")])
+        pr2, commits2 = repos.make_pr(2, "p2", [("f", "two\n", "c2")])
+        apply(gp, pr1, commits1, repos.work)
+        with pytest.raises(app.PatchError, match="CONFLICT"):
+            apply(gp, pr2, commits2, repos.work)
+        assert gp.roll_back() is True
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == before
+
+    def test_uncommitted_local_changes_survive(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        (repos.work / "f").write_text("base\nlocal edit\n")
+        apply(gp, pr, api_commits, repos.work)
+        assert gp.roll_back() is True
+        assert repos.work_log() == ["base"]
+        assert repos.work_file("f") == "base\nlocal edit\n"
+
+    def test_checkout_mode_restores_branch(self, config_file, repos):
+        gp = app.GitHubPatches.from_config_file(
+            config_file, checkout=True, use_ssh=False
+        )
+        pr, _ = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        gp.apply_single_pr(pr, str(repos.work))
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == pr.head_sha
+        assert gp.roll_back() is True
+        assert repos.git(repos.work, 'symbolic-ref', '--short',
+                         'HEAD') == 'master'
+        assert repos.work_log() == ["base"]
+
+    def test_detached_head_restored_detached(self, gp, repos):
+        base = repos.git(repos.work, 'rev-parse', 'HEAD')
+        repos.git(repos.work, 'checkout', '-q', '--detach')
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        apply(gp, pr, api_commits, repos.work)
+        assert gp.roll_back() is True
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == base
+        assert subprocess.run(
+            ['git', 'symbolic-ref', '-q', 'HEAD'], cwd=repos.work
+        ).returncode != 0
+
+    def test_mid_cherry_pick_aborted(self, gp, repos):
+        pr, api_commits = repos.make_pr(1, "p1", [("f", "theirs\n", "c1")])
+        repos.commit_file("f", "ours\n", "local", repo=repos.work)
+        before = repos.git(repos.work, 'rev-parse', 'HEAD')
+        with pytest.raises(app.PatchError):
+            apply(gp, pr, api_commits, repos.work)
+        assert gp.roll_back() is True
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == before
+        assert repos.git(repos.work, 'status', '--porcelain') == ''
+
+    def test_rollback_failure_reported(self, gp, repos, caplog):
+        pr, api_commits = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        apply(gp, pr, api_commits, repos.work)
+        # A local edit to a file the rollback must change blocks reset --keep
+        (repos.work / "g").write_text("edited\n")
+        assert gp.roll_back() is False
+        assert "Could not roll back" in caplog.text
+        assert "Restore it manually" in caplog.text
+        assert repos.work_file("g") == "edited\n"
+
+    def test_incomplete_rollback_reported(self, gp_with_manifest, caplog):
+        gp = gp_with_manifest
+        gp.originals = {"somewhere": ("master", "abc")}
+        with patch.object(gp, 'resolve_prs',
+                          side_effect=app.PatchError("it broke")), \
+             patch.object(gp, 'roll_back', return_value=False):
+            with pytest.raises(SystemExit) as e:
+                gp.patch_repo_sync([], 'pr')
+        assert e.value.code == 5
+        assert "Rollback incomplete" in caplog.text
+
+    @pytest.mark.parametrize('exc, logged', [
+        (KeyError('oops'), "Unexpected error: KeyError('oops')"),
+        (KeyboardInterrupt(), "Interrupted"),
+    ])
+    def test_other_exceptions_roll_back(
+        self, gp_with_manifest, caplog, exc, logged
+    ):
+        gp = gp_with_manifest
+        gp.originals = {"somewhere": ("master", "abc")}
+        with patch.object(gp, 'resolve_prs', side_effect=exc), \
+             patch.object(gp, 'roll_back', return_value=True) as mock_back:
+            with pytest.raises(SystemExit) as e:
+                gp.patch_repo_sync([], 'pr')
+        assert e.value.code == 5
+        mock_back.assert_called_once()
+        assert logged in caplog.text
+
+    @pytest.mark.parametrize('exc, code', [
+        (KeyError('oops'), 1), (KeyboardInterrupt(), 130),
+    ])
+    def test_other_exceptions_before_any_change(
+        self, gp_with_manifest, exc, code
+    ):
+        gp = gp_with_manifest
+        with patch.object(gp, 'resolve_prs', side_effect=exc):
+            with pytest.raises(SystemExit) as e:
+                gp.patch_repo_sync([], 'pr')
+        assert e.value.code == code
+
+
+# ===================================================================
+# apply_prs
+# ===================================================================
+
+class TestApplyPrs:
+
+    @pytest.mark.parametrize('project, path', [
+        ("server-ui", "server-ui"),
+        ("couchbase-cli", "couchbase-cli-tools"),
+    ])
+    def test_applied_at_manifest_path(self, gp_with_manifest, project, path):
+        gp = gp_with_manifest
+        pr = app.GitHubPR(make_pr_api_response(10, project))
+        with patch.object(gp, 'apply_single_pr') as mock_apply:
+            gp.apply_prs({pr.key: pr})
+        mock_apply.assert_called_once_with(pr, path)
+
+    def test_unknown_project_skipped(self, gp_with_manifest, caplog):
+        caplog.set_level(logging.INFO, logger='patch_via_github')
+        gp = gp_with_manifest
+        pr = app.GitHubPR(make_pr_api_response(30, "nonexistent-repo"))
+        with patch.object(gp, 'apply_single_pr') as mock_apply:
+            gp.apply_prs({pr.key: pr})
+        mock_apply.assert_not_called()
+        assert "ignoring PR couchbase/nonexistent-repo#30" in caplog.text
+
+    def test_prs_applied_in_given_order(self, gp_with_manifest):
+        gp = gp_with_manifest
+        pr10 = app.GitHubPR(make_pr_api_response(10, "couchbase-cli"))
+        pr2 = app.GitHubPR(
+            make_pr_api_response(2, "server-ui", base_ref="main")
+        )
+        applied_order = []
+
+        with patch.object(gp, 'apply_single_pr',
+                          side_effect=lambda pr, *a, **k:
+                          applied_order.append(pr.ref)):
+            gp.apply_prs({pr10.key: pr10, pr2.key: pr2})
+
+        assert applied_order == [
+            "couchbase/couchbase-cli#10", "couchbase/server-ui#2"
+        ]
+
+
+# ===================================================================
+# patch_repo_sync — Top-Level Orchestration
+# ===================================================================
+
+def pr_for(project, number):
+    return app.GitHubPR(make_pr_api_response(number, project))
+
+
+class TestPatchRepoSync:
+
+    @pytest.fixture
+    def resolved(self):
+        prs = (pr_for("server-ui", 2), pr_for("couchbase-cli", 3))
+        return {pr.key: pr for pr in prs}
+
+    def run(self, gp, resolved, applied):
+        """patch_repo_sync with only PRs to the projects in applied applying"""
+
+        def apply(pr, *args):
+            if pr.project in applied:
+                gp.applied_prs.append(pr.key)
+
+        with patch.object(gp, 'resolve_prs', return_value=resolved), \
+             patch.object(gp, 'apply_single_pr',
+                          side_effect=apply) as mock_apply:
+            gp.patch_repo_sync(["refs"], 'pr')
+        return mock_apply
+
+    def test_unapplied_request_fails(self, gp_with_manifest, resolved, caplog):
+        with pytest.raises(SystemExit) as e:
+            self.run(gp_with_manifest, resolved, {"server-ui"})
+        assert e.value.code == 1
+        assert ("Failed to apply all explicitly-requested PRs! Requested: "
+                "['couchbase/server-ui#2', 'couchbase/couchbase-cli#3'] "
+                "Applied: ['couchbase/server-ui#2']") in caplog.text
+
+    def test_all_applied_passes(self, gp_with_manifest, resolved):
+        mock_apply = self.run(
+            gp_with_manifest, resolved, {"server-ui", "couchbase-cli"}
+        )
+        assert mock_apply.call_count == 2
+
+    def test_unapplied_request_rolls_back_applied_prs(
+        self, gp_with_manifest, resolved
+    ):
+        gp = gp_with_manifest
+        gp.originals = {"server-ui": ("master", "abc")}
+        with patch.object(gp, 'roll_back', return_value=True) as mock_back:
+            with pytest.raises(SystemExit) as e:
+                self.run(gp, resolved, {"server-ui"})
+        assert e.value.code == 5
+        mock_back.assert_called_once()
+
+    def test_failure_before_any_change_keeps_exit_code(
+        self, gp_with_manifest, caplog
+    ):
+        gp = gp_with_manifest
+        with patch.object(gp, 'resolve_prs',
+                          side_effect=app.PatchError("it broke")), \
+             patch.object(gp, 'roll_back') as mock_roll_back:
+            with pytest.raises(SystemExit) as e:
+                gp.patch_repo_sync(["couchbase/tlm#1"], 'pr')
+        assert e.value.code == 1
+        assert "it broke" in caplog.text
+        mock_roll_back.assert_not_called()
+
+
+# ===================================================================
+# main() — argument parsing
+# ===================================================================
+
+def set_argv(monkeypatch, *args):
+    monkeypatch.setattr(sys, 'argv', ['patch_via_github', *args])
+
+
+class TestMainArguments:
+
+    def test_requires_pr_or_label(self, monkeypatch, capsys):
+        set_argv(monkeypatch)
+        with pytest.raises(SystemExit) as e:
+            app.main()
+        assert e.value.code == 2
+        assert ("one of the arguments -p/--pull-request -l/--label is "
+                "required") in capsys.readouterr().err
+
+    def test_pr_and_label_mutually_exclusive(
+        self, monkeypatch, capsys, config_file
+    ):
+        set_argv(monkeypatch, '-c', config_file,
+                 '-p', 'couchbase/tlm#1', '-l', 'couchbase/tlm:bug')
+        with pytest.raises(SystemExit) as e:
+            app.main()
+        assert e.value.code == 2
+        assert ("argument -l/--label: not allowed with argument "
+                "-p/--pull-request") in capsys.readouterr().err
+
+    def test_invalid_repo_source_exits(
+        self, monkeypatch, config_file, tmp_path, caplog
+    ):
+        set_argv(monkeypatch, '-c', config_file, '-p', 'couchbase/tlm#1',
+                 '-s', str(tmp_path / "does-not-exist"))
+        with pytest.raises(SystemExit) as e:
+            app.main()
+        assert e.value.code == 1
+        assert "Path for repo sync checkout doesn't exist" in caplog.text
+
+    @pytest.mark.parametrize('option', ['-p', '-l'])
+    def test_no_values_after_splitting_rejected(
+        self, monkeypatch, capsys, option
+    ):
+        set_argv(monkeypatch, option, ',')
+        with pytest.raises(SystemExit) as e:
+            app.main()
+        assert e.value.code == 2
+        assert f"argument {option}: expected a value" in (
+            capsys.readouterr().err
+        )
+
+    def test_config_error_exits(self, monkeypatch, tmp_path, caplog):
+        ini = tmp_path / "bad.ini"
+        ini.write_text("[main]\nghp_SECRET\n")
+        set_argv(monkeypatch, '-c', str(ini), '-s', str(tmp_path),
+                 '-p', 'couchbase/tlm#1')
+        with pytest.raises(SystemExit) as e:
+            app.main()
+        assert e.value.code == 1
+        assert "could not parse line 2" in caplog.text
+        assert "SECRET" not in caplog.text
+
+
+# ===================================================================
+# main() — end to end against real git repositories
+# ===================================================================
+
+MANIFEST = b'<manifest><default revision="master"/><project name="work"/>' \
+    b'</manifest>'
+
+
+class TestMainEndToEnd:
+
+    @pytest.fixture
+    def ini(self, tmp_path):
+        return write_ini(tmp_path, "token = x", "ssh = false")
+
+    @pytest.fixture
+    def run_main(self, monkeypatch, repos):
+        """Run main() from outside the repo sync, with -s pointing at it"""
+        elsewhere = repos.root / "elsewhere"
+        elsewhere.mkdir()
+        monkeypatch.chdir(elsewhere)
+        monkeypatch.setenv('LD_LIBRARY_PATH', '/pyinstaller/libs')
+
+        def run(*args):
+            set_argv(monkeypatch, '-s', str(repos.root), *args)
+            with patch.object(app, 'which', return_value='/usr/bin/repo'), \
+                 patch('subprocess.check_output', return_value=MANIFEST), \
+                 patch.object(app.GitHubPatches, '_api_get',
+                              side_effect=repos.api_get), \
+                 patch.object(app.GitHubPatches, '_api_get_paginated',
+                              side_effect=repos.api_get):
+                app.main()
+
+        return run
+
+    def test_closed_pr_requested_explicitly_is_applied(
+        self, run_main, repos, ini, capsys
+    ):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")], state="closed")
+        run_main('-c', ini, '-p', 'Couchbase/Work#1,couchbase/work#1')
+        assert repos.work_log() == ["c1", "base"]
+        err = capsys.readouterr().err
+        assert err.count("***** Applying") == 1
+        assert "All explicitly-requested PRs applied" in err
+        assert "DEBUG:" not in err
+        assert 'LD_LIBRARY_PATH' not in os.environ
+
+    def test_prs_applied_in_requested_order(self, run_main, repos, ini):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        repos.make_pr(2, "p2", [("h", "two\n", "c2")])
+        run_main('-c', ini, '-p', 'couchbase/work#2,couchbase/work#1')
+        assert repos.work_log() == ["c1", "c2", "base"]
+
+    def test_short_ref_uses_default_org_option(self, run_main, repos, ini):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        run_main('-c', ini, '-p', 'work#1', '-o', 'couchbase')
+        assert repos.endpoints[0] == '/repos/couchbase/work/pulls/1'
+        assert repos.work_log() == ["c1", "base"]
+
+    def test_checkout_option(self, run_main, repos, ini):
+        pr, _ = repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        repos.commit_file("h", "local\n", "local", repo=repos.work)
+        run_main('-c', ini, '-C', '-p', 'couchbase/work#1')
+        assert repos.git(repos.work, 'rev-parse', 'HEAD') == pr.head_sha
+
+    def test_label_applies_open_labelled_prs(
+        self, run_main, repos, ini, capsys
+    ):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")], labels=["lbl"])
+        repos.make_pr(2, "p2", [("h", "two\n", "c2")], labels=["other"])
+        run_main('-c', ini, '-l', 'couchbase/work:lbl')
+        assert repos.work_log() == ["c1", "base"]
+        assert ("Applied PRs from label(s) 'couchbase/work:lbl': "
+                "['couchbase/work#1']") in capsys.readouterr().err
+
+    def test_unapplied_request_rolls_back(
+        self, run_main, repos, ini, capsys
+    ):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        repos.make_pr(2, "p2", [("x", "two\n", "c2")], project="gone")
+        with pytest.raises(SystemExit) as e:
+            run_main('-c', ini, '-p', 'couchbase/work#1,couchbase/gone#2')
+        assert e.value.code == 5
+        err = capsys.readouterr().err
+        assert "ignoring PR couchbase/gone#2" in err
+        assert "Failed to apply all explicitly-requested PRs" in err
+        assert repos.work_log() == ["base"]
+
+    def test_ini_ssh_used_for_fetch(self, run_main, repos, tmp_path, capsys):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        with pytest.raises(SystemExit) as e:
+            run_main('-c', write_ini(tmp_path, "token = x", "ssh = true"),
+                     '-p', 'couchbase/work#1')
+        assert e.value.code == 5
+        assert f"git fetch {repos.root / 'ssh-unreachable'}" in (
+            capsys.readouterr().err
+        )
+        assert repos.work_log() == ["base"]
+
+    def test_no_ssh_option_overrides_ini(self, run_main, repos, tmp_path):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        run_main('-c', write_ini(tmp_path, "token = x", "ssh = true"),
+                 '--no-ssh', '-p', 'couchbase/work#1')
+        assert repos.work_log() == ["c1", "base"]
+
+    def test_debug_option(self, run_main, repos, ini, capsys):
+        repos.make_pr(1, "p1", [("g", "one\n", "c1")])
+        run_main('-c', ini, '-d', '-p', 'couchbase/work#1')
+        assert "DEBUG: Fetching PR couchbase/work#1" in (
+            capsys.readouterr().err
+        )