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

patch_via_github/scripts/main.py

@@ -0,0 +1,965 @@
+#!/usr/bin/env python3
+
+"""
+Basic program to apply a set of patches from various GitHub pull requests
+based on user criteria to a repo sync area
+
+PRs are applied in the order requested; PRs found by label are applied in
+the order the labels were given, and in PR number order for each label
+"""
+
+import argparse
+import configparser
+import contextlib
+import logging
+import os
+import re
+import subprocess
+import sys
+import time
+import xml.etree.ElementTree as EleTree
+from importlib.metadata import version
+from shutil import which
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.auth import AuthBase
+from urllib3.util.retry import Retry
+
+
+logger = logging.getLogger('patch_via_github')
+
+SHA_RE = re.compile(r'^[0-9a-f]{40}$')
+# GitHub caps a PR's commit listing at this many commits
+MAX_LISTED_COMMITS = 250
+# Seconds
+FETCH_TIMEOUT = 10 * 60
+REPO_MANIFEST_TIMEOUT = 5 * 60
+
+
+class PatchError(RuntimeError):
+    """A failure reported to the user before exiting"""
+
+    def __init__(self, message, exit_code=1):
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def pr_key(repo_full_name, number):
+    """Identity of a PR across repos; GitHub names are case-insensitive"""
+    return f'{repo_full_name.lower()}#{int(number)}'
+
+
+@contextlib.contextmanager
+def api_data(what):
+    """Report malformed GitHub API data as a PatchError"""
+    try:
+        yield
+    except (KeyError, TypeError) as exc:
+        raise PatchError(
+            f'GitHub API error: unexpected {what} '
+            f'(missing or malformed field {exc})'
+        ) from exc
+
+
+def run_git(cwd, *args, timeout=None, text=True, input=None):
+    """Run git in cwd, capturing its output"""
+
+    logger.debug(f'  git {" ".join(args)} (in {cwd})')
+    try:
+        return subprocess.run(
+            ['git', *args], cwd=cwd, capture_output=True, text=text,
+            input=input, timeout=timeout
+        )
+    except OSError as exc:
+        raise PatchError(f'Could not run git in {cwd}: {exc}') from exc
+    except subprocess.TimeoutExpired as exc:
+        raise PatchError(
+            f'`git {" ".join(args)}` in {cwd} timed out after {timeout}s'
+        ) from exc
+
+
+def repo_tool():
+    repo = which('repo')
+    if repo is None:
+        raise PatchError("'repo' tool not found on PATH")
+    return repo
+
+
+class BearerAuth(AuthBase):
+    """Token auth; set as the session's auth so ~/.netrc can't override it"""
+
+    def __init__(self, token):
+        self.token = token
+
+    def __call__(self, request):
+        request.headers['Authorization'] = f'Bearer {self.token}'
+        return request
+
+
+class GitHubPR:
+    """Encapsulation of relevant information for a given GitHub pull request"""
+
+    def __init__(self, data, use_ssh=False):
+        """
+        Initialize with key information for a GitHub PR
+        """
+        self.number = int(data['number'])
+        self.repo_full_name = data['base']['repo']['full_name']
+        self.project = data['base']['repo']['name']
+        self.branch = data['base']['ref']
+        self.head_sha = data['head']['sha']
+        self.html_url = data['html_url']
+        # Only the single-PR endpoint reports this, not the PR listing
+        self.commit_count = data.get('commits')
+        self.ref = f'{self.repo_full_name}#{self.number}'
+        self.key = pr_key(self.repo_full_name, self.number)
+        # Populated by GitHubPatches.load_pr_commits before cherry-picking
+        self.commits = []
+        self.fetch_url = data['base']['repo'][
+            'ssh_url' if use_ssh else 'clone_url'
+        ]
+
+
+class GitHubPatches:
+    """
+    Determine all relevant patches to apply to a repo sync based on
+    a given set of initial parameters, which can be a set of one of
+    the following:
+        - PR references (org/repo#number or repo#number)
+        - labels (org/repo:label)
+
+    The resulting data will include the necessary patch commands to
+    be applied to the repo sync
+    """
+
+    GITHUB_API_URL = 'https://api.github.com'
+
+    def __init__(self, token, default_org=None, checkout=False, use_ssh=True):
+        """Initial GitHub connection and set base options"""
+
+        self.default_org = default_org
+        self.checkout = checkout
+        self.use_ssh = use_ssh
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Accept': 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        })
+        self.session.auth = BearerAuth(token)
+        retry = Retry(
+            total=3, backoff_factor=1, allowed_methods={'GET'},
+            status_forcelist={429, 500, 502, 503, 504},
+            retry_after_max=60, raise_on_status=False,
+        )
+        self.session.mount('https://', HTTPAdapter(max_retries=retry))
+
+        # pr_key() of each PR applied, in order
+        self.applied_prs = []
+        # Read from 'repo manifest' on first use
+        self.manifest = None
+        # proj_path -> (branch or None if detached, HEAD sha) before this
+        # run first touched it, for rolling back on failure
+        self.originals = {}
+
+    @classmethod
+    def from_config_file(cls, config_path, default_org=None, checkout=False,
+                         use_ssh=None):
+        """
+        Factory method: construct a GitHubPatches from the path to a
+        config file
+        """
+        config = configparser.ConfigParser()
+        try:
+            with open(config_path) as config_file:
+                config.read_file(config_file)
+        except FileNotFoundError:
+            raise PatchError(
+                f'Configuration file {config_path} missing!'
+            ) from None
+        except OSError as exc:
+            raise PatchError(
+                f'Could not read configuration file {config_path}: '
+                f'{exc.strerror}'
+            ) from None
+        except configparser.Error as exc:
+            # Not quoting exc: it includes the offending line, maybe the token
+            errors = (getattr(exc, 'errors', None)
+                      or [(getattr(exc, 'lineno', '?'), None)])
+            lines = ', '.join(str(lineno) for lineno, _ in errors)
+            raise PatchError(
+                f'Invalid config file "{config_path}" (could not parse '
+                f'line {lines})'
+            ) from None
+
+        if 'main' not in config.sections():
+            raise PatchError(
+                f'Invalid config file "{config_path}" '
+                '(missing "main" section)'
+            )
+
+        token = config.get('main', 'token', fallback=None)
+        if token is None:
+            raise PatchError(
+                'Required option "token" is missing from the config '
+                'file. Aborting...'
+            )
+        if not token:
+            raise PatchError(
+                f'Option "token" in {config_path} is empty. Aborting...'
+            )
+
+        org = default_org or config.get('main', 'default_org', fallback=None)
+
+        ssh = use_ssh
+        if ssh is None:
+            try:
+                ssh = config.getboolean('main', 'ssh', fallback=True)
+            except ValueError:
+                raise PatchError(
+                    f'Invalid value for "ssh" in {config_path}: '
+                    f'"{config.get("main", "ssh")}" (expected true or false)'
+                ) from None
+
+        return cls(token, org, checkout, ssh)
+
+    def patch_repo_sync(self, refs, id_type):
+        """
+        Patch the repo sync with the list of patch commands. Repo
+        sync is presumed to be in current working directory.
+        """
+
+        try:
+            prs = self.resolve_prs(refs, id_type)
+            self.apply_prs(prs)
+            self.check_requested_prs_applied(id_type, refs, prs)
+        except (Exception, KeyboardInterrupt) as exc:
+            self._abort(exc)
+
+    def resolve_prs(self, refs, id_type):
+        """
+        From an initial set of PR references or labels, determine all
+        relevant PRs that will need to be applied to a repo sync
+        via patching
+        """
+
+        if id_type == 'pr':
+            prs = self._resolve_pr_refs(refs)
+        else:
+            prs = self._resolve_labels(refs)
+        logger.info(
+            f'Final list of PRs to apply: '
+            f'{", ".join(pr.ref for pr in prs.values())}'
+        )
+        return prs
+
+    def _resolve_pr_refs(self, pr_refs):
+        """Requested PRs are applied whatever their state or target branch"""
+
+        parsed = [self.parse_pr_reference(ref) for ref in pr_refs]
+        prs = {}
+        for org, repo, number in parsed:
+            try:
+                pr = self.get_pr(org, repo, number)
+            except PatchError as exc:
+                raise PatchError(
+                    f'Failed to fetch {org}/{repo}#{number}: {exc}'
+                ) from exc
+            # GitHub follows repo renames, so pr.key is the canonical name
+            prs.setdefault(pr.key, pr)
+        return prs
+
+    def parse_pr_reference(self, pr_ref):
+        """
+        Parse a PR reference into (org, repo, number).
+        Supports formats:
+            - org/repo#number
+            - repo#number (uses default_org)
+        """
+
+        # Full format: org/repo#number
+        match = re.match(r'^([^/]+)/([^#]+)#(\d+)$', pr_ref)
+        if match:
+            return match.groups()
+
+        # Short format: repo#number
+        match = re.match(r'^([^#/]+)#(\d+)$', pr_ref)
+        if match:
+            if not self.default_org:
+                raise PatchError(
+                    f'PR reference "{pr_ref}" needs an org, but no '
+                    'default_org configured. Use org/repo#number format '
+                    'or set default_org in config.'
+                )
+            return self.default_org, *match.groups()
+
+        raise PatchError(
+            f'Invalid PR reference: "{pr_ref}". '
+            'Use format: org/repo#number or repo#number'
+        )
+
+    def _resolve_labels(self, label_refs):
+        """Open labelled PRs, if they target their project's manifest branch"""
+
+        parsed = []
+        for label_ref in label_refs:
+            match = re.match(r'^([^/]+)/([^:]+):(.+)$', label_ref)
+            if not match:
+                raise PatchError(
+                    f'Invalid label reference: "{label_ref}". '
+                    'Use format: org/repo:label'
+                )
+            parsed.append((label_ref, *match.groups()))
+
+        prs = {}
+        for label_ref, org, repo, label in parsed:
+            try:
+                labelled = self.get_open_prs_by_label(org, repo, label)
+            except PatchError as exc:
+                raise PatchError(
+                    f'Failed to fetch PRs for {label_ref}: {exc}'
+                ) from exc
+            for pr in sorted(labelled.values(), key=lambda pr: pr.number):
+                prs.setdefault(pr.key, pr)
+
+        for key, pr in list(prs.items()):
+            _, manifest_branch = (
+                self.get_project_path_and_branch_from_manifest(pr.project)
+            )
+            if (manifest_branch
+                    and pr.branch != manifest_branch
+                    and not SHA_RE.match(manifest_branch)):
+                logger.info(
+                    f'  Ignoring {pr.ref} because it targets {pr.branch}, '
+                    f'manifest branch is {manifest_branch}'
+                )
+                del prs[key]
+        return prs
+
+    def get_pr(self, org, repo, number):
+        """Fetch a single PR from GitHub API"""
+
+        logger.debug(f'Fetching PR {org}/{repo}#{number}')
+        data = self._api_get(f'/repos/{org}/{repo}/pulls/{number}')
+        return self._make_pr(data, f'{org}/{repo}#{number}')
+
+    def get_open_prs_by_label(self, org, repo, label):
+        """Fetch all open PRs with a given label"""
+
+        logger.debug(
+            f'Fetching open PRs with label "{label}" from {org}/{repo}'
+        )
+        data = self._api_get_paginated(
+            f'/repos/{org}/{repo}/pulls?state=open&per_page=100'
+        )
+        with api_data(f'PR data from {org}/{repo}'):
+            labelled = [
+                pr_data for pr_data in data
+                if label in (lbl['name'] for lbl in pr_data['labels'])
+            ]
+        prs = {}
+        for pr_data in labelled:
+            pr = self._make_pr(pr_data, f'{org}/{repo}')
+            prs[pr.key] = pr
+        return prs
+
+    def _make_pr(self, data, source):
+        with api_data(f'PR data from {source}'):
+            return GitHubPR(data, use_ssh=self.use_ssh)
+
+    def get_project_path_and_branch_from_manifest(self, project):
+        """(path, revision) of project, or (None, None) if not in manifest"""
+
+        if self.manifest is None:
+            self._load_manifest()
+
+        proj_info = self.manifest.find(f'.//project[@name="{project}"]')
+        if proj_info is None:
+            return None, None
+
+        # Same precedence as repo: project, then its remote, then <default>
+        default = self.manifest.find('.//default')
+        defaults = {} if default is None else default.attrib
+        branch = proj_info.get('revision')
+        if branch is None:
+            remote_name = proj_info.get('remote', defaults.get('remote'))
+            remote = self.manifest.find(f'.//remote[@name="{remote_name}"]')
+            if remote is not None:
+                branch = remote.get('revision')
+        if branch is None:
+            branch = defaults.get('revision')
+        if branch is not None:
+            branch = branch.removeprefix('refs/heads/')
+        return proj_info.get('path', project), branch
+
+    def _load_manifest(self):
+        try:
+            manifest_str = subprocess.check_output(
+                [repo_tool(), 'manifest'], timeout=REPO_MANIFEST_TIMEOUT
+            )
+        except subprocess.CalledProcessError as exc:
+            raise PatchError(
+                f"'repo manifest' failed with exit code {exc.returncode}"
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise PatchError(
+                f"'repo manifest' timed out after {exc.timeout}s"
+            ) from exc
+        except OSError as exc:
+            raise PatchError(f"Could not run 'repo manifest': {exc}") from exc
+        try:
+            self.manifest = EleTree.fromstring(manifest_str)
+        except EleTree.ParseError as exc:
+            raise PatchError(
+                f"Could not parse 'repo manifest' output: {exc}"
+            ) from exc
+
+    def apply_prs(self, prs):
+        """Applies the given PRs, in order"""
+
+        for pr in prs.values():
+            path, _ = self.get_project_path_and_branch_from_manifest(
+                pr.project
+            )
+            if path is None:
+                logger.info(
+                    f"***** NOTE: ignoring PR {pr.ref} for project "
+                    f"{pr.project} that is either not part of the "
+                    f"manifest, or was excluded due to manifest "
+                    f"group filters."
+                )
+                continue
+
+            self.apply_single_pr(pr, path)
+
+    def apply_single_pr(self, pr, proj_path):
+        """
+        Given a single PR object and a path, apply the git change to
+        that path (using either checkout or cherry-pick as requested).
+        """
+
+        if not os.path.exists(proj_path):
+            raise PatchError(
+                f'***** Project {pr.project} missing on disk! '
+                f'Expected to be in {proj_path}',
+                exit_code=5
+            )
+        self._record_original(proj_path)
+
+        logger.info(
+            f'***** Applying {pr.html_url} to project {pr.project}:'
+        )
+        if not self.checkout:
+            self.load_pr_commits(pr)
+
+        self._git(pr, proj_path, 'fetch', pr.fetch_url,
+                  f'pull/{pr.number}/head', timeout=FETCH_TIMEOUT)
+        fetched = self._git(pr, proj_path, 'rev-parse', 'FETCH_HEAD').strip()
+        if fetched != pr.head_sha:
+            raise PatchError(
+                f'{pr.ref}: fetched {fetched} but GitHub reported head '
+                f'{pr.head_sha}; the PR was updated during this run, '
+                're-run it'
+            )
+
+        if self.checkout:
+            self._git(pr, proj_path, 'checkout', 'FETCH_HEAD')
+        else:
+            self._cherry_pick_commits(pr, proj_path)
+        logger.info(
+            f'***** Done applying PR {pr.ref} '
+            f'to project {pr.project}\n'
+        )
+        self.applied_prs.append(pr.key)
+
+    def _record_original(self, proj_path):
+        if proj_path in self.originals:
+            return
+        head = run_git(proj_path, 'rev-parse', 'HEAD')
+        if head.returncode != 0:
+            raise PatchError(
+                f'{proj_path} is not a usable git checkout: '
+                f'{head.stderr.strip()}'
+            )
+        branch = run_git(
+            proj_path, 'symbolic-ref', '-q', '--short', 'HEAD'
+        ).stdout.strip() or None
+        self.originals[proj_path] = (branch, head.stdout.strip())
+
+    def load_pr_commits(self, pr):
+        """
+        Record the PR's own commits, oldest first, for cherry-picking.
+        Requires linear history, and a commit list that GitHub confirms
+        is complete
+        """
+
+        if pr.commit_count is None:
+            org, repo = pr.repo_full_name.split('/', 1)
+            latest = self.get_pr(org, repo, pr.number)
+            if latest.head_sha != pr.head_sha:
+                raise PatchError(
+                    f'{pr.ref}: head moved from {pr.head_sha} to '
+                    f'{latest.head_sha} during this run; re-run it'
+                )
+            pr.commit_count = latest.commit_count
+
+        if not isinstance(pr.commit_count, int):
+            raise PatchError(
+                f'GitHub API error: no commit count reported for {pr.ref}'
+            )
+        if pr.commit_count > MAX_LISTED_COMMITS:
+            raise PatchError(
+                f'{pr.ref} has {pr.commit_count} commits, but GitHub only '
+                f'lists {MAX_LISTED_COMMITS}, so they cannot all be '
+                'cherry-picked. Use --checkout, or split the PR'
+            )
+
+        data = self._api_get_paginated(
+            f'/repos/{pr.repo_full_name}/pulls/{pr.number}/commits'
+            '?per_page=100'
+        )
+        with api_data(f'commit data for {pr.ref}'):
+            parents = {
+                commit['sha']: [parent['sha'] for parent in commit['parents']]
+                for commit in data
+            }
+
+        if len(parents) != pr.commit_count:
+            raise PatchError(
+                f'{pr.ref}: GitHub reports {pr.commit_count} commits but '
+                f'listed {len(parents)}; the PR may have been updated '
+                'during this run, re-run it'
+            )
+        if pr.head_sha not in parents:
+            raise PatchError(
+                f'{pr.ref}: PR head {pr.head_sha} is not in the commit list '
+                'from GitHub; the PR may have been updated during this run, '
+                're-run it'
+            )
+
+        shas = []
+        sha = pr.head_sha
+        while sha in parents:
+            if len(parents[sha]) != 1:
+                raise PatchError(
+                    f'{pr.ref}: commit {sha} is a merge commit; '
+                    'cherry-picking needs linear PR history. Rebase the PR '
+                    'or use --checkout'
+                )
+            shas.append(sha)
+            sha = parents[sha][0]
+
+        if len(shas) != len(parents):
+            stray = sorted(set(parents) - set(shas))
+            raise PatchError(
+                f'{pr.ref}: commits {", ".join(stray)} are not ancestors of '
+                f'the PR head {pr.head_sha}; the PR may have been updated '
+                'during this run, re-run it'
+            )
+        pr.commits = shas[::-1]
+
+    def _cherry_pick_commits(self, pr, proj_path):
+        """
+        Cherry-pick the PR's commits one at a time, skipping any whose
+        changes are already present (e.g. from a stacked PR applied earlier)
+        """
+
+        present = self._present_prefix(pr, proj_path)
+        if present:
+            logger.info(
+                f'  Skipped the first {present} commit(s), up to '
+                f'{pr.commits[present - 1]}: their changes are already '
+                'present (e.g. from a stacked PR applied earlier)'
+            )
+
+        picked = 0
+        for sha in pr.commits[present:]:
+            result = run_git(proj_path, 'cherry-pick', sha)
+            if result.returncode == 0:
+                picked += 1
+                continue
+            if not self._cherry_pick_is_empty(proj_path):
+                self._raise_git_error(
+                    pr, proj_path, ('cherry-pick', sha), result
+                )
+            self._git(pr, proj_path, 'cherry-pick', '--skip')
+            empty_in_pr = run_git(
+                proj_path, 'diff', '--quiet', f'{sha}^', sha
+            ).returncode == 0
+            reason = ('it is empty in the PR' if empty_in_pr
+                      else 'its changes are already present')
+            logger.info(f'  Skipped commit {sha}: {reason}')
+
+        logger.info(
+            f'  Cherry-picked {picked} of {len(pr.commits)} commit(s)'
+        )
+        if not picked:
+            logger.warning(
+                f'  {pr.ref} added no new changes to {pr.project}'
+            )
+
+    def _present_prefix(self, pr, proj_path):
+        """
+        Length of the longest leading run of the PR's commits whose combined
+        changes already exist in the checkout, i.e. their diff
+        reverse-applies
+        """
+
+        base = f'{pr.commits[0]}^'
+        for count in range(len(pr.commits), 0, -1):
+            diff_args = ('diff', '--binary', base, pr.commits[count - 1])
+            diff = run_git(proj_path, *diff_args, text=False)
+            if diff.returncode != 0:
+                self._raise_git_error(pr, proj_path, diff_args, diff)
+            if run_git(
+                proj_path, 'apply', '--check', '--reverse',
+                text=False, input=diff.stdout
+            ).returncode == 0:
+                return count
+        return 0
+
+    @staticmethod
+    def _cherry_pick_is_empty(proj_path):
+        """True if a stopped cherry-pick has no conflicts and nothing staged"""
+
+        return (
+            run_git(proj_path, 'rev-parse', '-q', '--verify',
+                    'CHERRY_PICK_HEAD').returncode == 0
+            and run_git(proj_path, 'ls-files', '--unmerged').stdout == ''
+            and run_git(proj_path, 'diff', '--cached',
+                        '--quiet').returncode == 0
+        )
+
+    def _git(self, pr, proj_path, *args, timeout=None):
+        """Run a git command for a PR, returning stdout"""
+
+        result = run_git(proj_path, *args, timeout=timeout)
+        if result.returncode != 0:
+            self._raise_git_error(pr, proj_path, args, result)
+        return result.stdout
+
+    @staticmethod
+    def _raise_git_error(pr, proj_path, args, result):
+        outputs = (
+            out.decode(errors='replace') if isinstance(out, bytes) else out
+            for out in (result.stdout, result.stderr)
+        )
+        output = '\n'.join(
+            out.strip() for out in outputs if out and out.strip()
+        )
+        msg = (
+            f'Failed to apply {pr.ref} to project {pr.project} '
+            f'({proj_path}): `git {" ".join(args)}` exited with code '
+            f'{result.returncode}'
+        )
+        if output:
+            msg += f'\n{output}'
+        if args[0] == 'cherry-pick':
+            msg += (
+                f'\n{proj_path} is left mid-cherry-pick; run '
+                '`git cherry-pick --abort` there to reset it'
+            )
+        raise PatchError(msg)
+
+    def check_requested_prs_applied(self, id_type, refs, requested):
+        """
+        Verify that every requested PR (keys of those resolved from the
+        request) was applied, raising PatchError if not
+        """
+
+        if id_type == 'label':
+            if self.applied_prs:
+                labels = ', '.join(f"'{ref}'" for ref in refs)
+                logger.info(
+                    f'Applied PRs from label(s) {labels}: {self.applied_prs}'
+                )
+            return
+
+        requested = list(requested)
+        if any(key not in self.applied_prs for key in requested):
+            raise PatchError(
+                'Failed to apply all explicitly-requested PRs! '
+                f'Requested: {requested} Applied: {self.applied_prs}'
+            )
+        if requested:
+            logger.info(
+                'All explicitly-requested PRs applied! '
+                f'Requested: {requested} Applied: {self.applied_prs}'
+            )
+
+    def _abort(self, exc):
+        """Report a failed run, roll back what it changed, and exit"""
+
+        if isinstance(exc, PatchError):
+            logger.critical(exc)
+        elif isinstance(exc, KeyboardInterrupt):
+            logger.critical('Interrupted')
+        else:
+            logger.critical(f'Unexpected error: {exc!r}', exc_info=exc)
+
+        if not self.originals:
+            if isinstance(exc, KeyboardInterrupt):
+                sys.exit(130)
+            sys.exit(getattr(exc, 'exit_code', 1))
+
+        logger.critical(
+            'Rolling back changes made by this run (PRs applied: '
+            f'{", ".join(self.applied_prs) or "none"})'
+        )
+        if not self.roll_back():
+            logger.critical(
+                'Rollback incomplete; see above for projects needing '
+                'manual attention'
+            )
+        sys.exit(5)
+
+    def roll_back(self):
+        """
+        Return every project this run touched to its original HEAD,
+        keeping uncommitted local changes. Returns True if all succeeded
+        """
+
+        ok = True
+        for proj_path, (branch, sha) in reversed(self.originals.items()):
+            target = f'{branch} at {sha}' if branch else sha
+            if run_git(proj_path, 'rev-parse', '-q', '--verify',
+                       'CHERRY_PICK_HEAD').returncode == 0:
+                run_git(proj_path, 'cherry-pick', '--abort')
+            if branch:
+                steps = [('checkout', '-q', branch),
+                         ('reset', '-q', '--keep', sha)]
+            else:
+                steps = [('checkout', '-q', '--detach', sha)]
+            for step in steps:
+                result = run_git(proj_path, *step)
+                if result.returncode != 0:
+                    logger.critical(
+                        f'  Could not roll back {proj_path}: '
+                        f'`git {" ".join(step)}` failed: '
+                        f'{result.stderr.strip()}. Restore it manually to '
+                        f'{target}'
+                    )
+                    ok = False
+                    break
+            else:
+                logger.critical(f'  Rolled back {proj_path} to {target}')
+        return ok
+
+    def _api_get(self, endpoint):
+        """Make a GET request to the GitHub API"""
+
+        return self._request(f'{self.GITHUB_API_URL}{endpoint}')[1]
+
+    def _api_get_paginated(self, endpoint):
+        """Make paginated GET requests to the GitHub API"""
+
+        results = []
+        url = f'{self.GITHUB_API_URL}{endpoint}'
+        while url:
+            response, data = self._request(url)
+            if not isinstance(data, list):
+                raise PatchError(
+                    f'GitHub API error: expected a list from {url}, got '
+                    f'{type(data).__name__}: {str(data)[:200]}'
+                )
+            results.extend(data)
+            url = response.links.get('next', {}).get('url')
+            # The token goes with every request, so stay on the API host
+            if url and not url.startswith(f'{self.GITHUB_API_URL}/'):
+                raise PatchError(
+                    f'GitHub API error: refusing to follow pagination link '
+                    f'to {url}'
+                )
+        return results
+
+    def _request(self, url):
+        """GET a GitHub API URL, returning (response, decoded JSON)"""
+
+        logger.debug(f'  API GET: {url}')
+        try:
+            response = self.session.get(url, timeout=30)
+            response.raise_for_status()
+            return response, response.json()
+        except requests.exceptions.HTTPError as exc:
+            raise PatchError(self._http_error_message(exc)) from exc
+        except requests.exceptions.JSONDecodeError as exc:
+            raise PatchError(
+                f'GitHub API error: invalid JSON from {url}: {exc}'
+            ) from exc
+        except requests.exceptions.RequestException as exc:
+            raise PatchError(
+                f'GitHub API error: request to {url} failed: {exc}'
+            ) from exc
+
+    @staticmethod
+    def _http_error_message(exc):
+        response = exc.response
+        if response is None:
+            return f'GitHub API error: {exc}'
+
+        msg = (
+            f'GitHub API error: {response.status_code} {response.reason} '
+            f'for {response.url}'
+        )
+        try:
+            detail = response.json().get('message')
+        except (ValueError, AttributeError):
+            detail = None
+        if detail:
+            msg += f' ({detail})'
+
+        headers = response.headers
+        if response.status_code == 401:
+            msg += ' - check the token in your config file'
+        elif (response.status_code in (403, 429)
+                and headers.get('X-RateLimit-Remaining') == '0'):
+            msg += ' - API rate limit exhausted'
+            reset = headers.get('X-RateLimit-Reset')
+            if reset and reset.isdigit():
+                reset_at = time.strftime(
+                    '%H:%M:%S %Z', time.localtime(int(reset))
+                )
+                msg += f', resets at {reset_at}'
+            elif reset:
+                msg += f', X-RateLimit-Reset: {reset}'
+        elif (response.status_code in (403, 429)
+                and headers.get('Retry-After')):
+            msg += (
+                ' - secondary rate limit hit, retry after '
+                f'{headers["Retry-After"]} seconds'
+            )
+        elif response.status_code == 403:
+            msg += (
+                ' - check your token has access to the repository, and is '
+                'authorized for the organization if it uses SSO'
+            )
+        elif response.status_code == 404:
+            msg += (
+                ' - check the reference is correct and that your token '
+                'can access the repository'
+            )
+        return msg
+
+
+class ParseCSVs(argparse.Action):
+    """Split each argument on commas, dropping empty values"""
+
+    def __call__(self, parser, namespace, arguments, option_string=None):
+        values = [
+            value for arg in arguments for value in arg.split(',') if value
+        ]
+        if not values:
+            parser.error(f'argument {option_string}: expected a value')
+        setattr(namespace, self.dest, values)
+
+
+def default_ini_file():
+    """
+    Returns a string path to the default patch_via_github.ini
+    """
+    return os.path.expanduser('~/.ssh/patch_via_github.ini')
+
+
+def print_divider():
+    """Print a visual divider line"""
+    print("=" * 80)
+
+
+def setup_logging():
+    """Log to stderr at INFO; returns the handler so --debug can lower it"""
+
+    logger.setLevel(logging.DEBUG)
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter('%(levelname)s: %(message)s'))
+    handler.setLevel(logging.INFO)
+    logger.addHandler(handler)
+    return handler
+
+
+def main():
+    """
+    Parse the arguments, verify the repo sync exists, read and validate
+    the configuration file, then determine all the needed GitHub PR
+    patches and apply them to the repo sync
+    """
+
+    # PyInstaller binaries get LD_LIBRARY_PATH set for them, and that
+    # can have unwanted side-effects for our subprocesses.
+    os.environ.pop("LD_LIBRARY_PATH", None)
+
+    handler = setup_logging()
+
+    version_string = (
+        f"patch_via_github version {version('patch-via-github')}"
+    )
+    parser = argparse.ArgumentParser(
+        description='Patch repo sync with requested GitHub pull requests'
+    )
+    parser.add_argument('-d', '--debug', action='store_true',
+                        help='Enable debugging output')
+    parser.add_argument('-c', '--config', dest='github_config',
+                        help='Configuration file for patching via GitHub',
+                        default=default_ini_file())
+    change_group = parser.add_mutually_exclusive_group(required=True)
+    change_group.add_argument(
+        '-p', '--pull-request', dest='pull_requests', nargs='+',
+        action=ParseCSVs,
+        help='Pull request references to apply (comma-separated). '
+             'Format: org/repo#number or repo#number (with -o)')
+    change_group.add_argument(
+        '-l', '--label', dest='labels', nargs='+',
+        action=ParseCSVs,
+        help='Labels to search for open PRs (comma-separated). '
+             'Format: org/repo:label')
+    parser.add_argument('-o', '--default-org', dest='default_org',
+                        help='Default GitHub organization for short-form '
+                             'PR references (repo#number)')
+    parser.add_argument('-s', '--source', dest='repo_source',
+                        help='Location of the repo sync checkout',
+                        default='.')
+    parser.add_argument('-C', '--checkout', action='store_true',
+                        help='When specified, checkout the PR head '
+                             'rather than cherry-picking')
+    parser.add_argument('--no-ssh', dest='use_ssh',
+                        action='store_false', default=None,
+                        help='Use HTTPS URLs for git fetch instead of '
+                             'SSH (also configurable via ini: ssh = false; '
+                             'this flag takes precedence)')
+    parser.add_argument('-V', '--version', action='version',
+                        help='Display patch_via_github version information',
+                        version=version_string)
+    args = parser.parse_args()
+
+    if args.debug:
+        handler.setLevel(logging.DEBUG)
+
+    if not os.path.isdir(args.repo_source):
+        logger.error(
+            "Path for repo sync checkout doesn't exist. Aborting..."
+        )
+        sys.exit(1)
+    os.chdir(args.repo_source)
+
+    if args.pull_requests:
+        id_type, refs = 'pr', args.pull_requests
+    else:
+        id_type, refs = 'label', args.labels
+
+    logger.info(f"******** {version_string} ********")
+    print_divider()
+    try:
+        github_patches = GitHubPatches.from_config_file(
+            args.github_config, args.default_org, args.checkout, args.use_ssh
+        )
+    except PatchError as exc:
+        logger.critical(exc)
+        sys.exit(exc.exit_code)
+
+    logger.info(f"Initial request to patch {id_type}s: {', '.join(refs)}")
+    github_patches.patch_repo_sync(refs, id_type)
+
+    print_divider()
+
+
+if __name__ == '__main__':
+    main()