github-backup 0.56.0__py3-none-any.whl → 0.58.0__py3-none-any.whl

github_backup/__init__.py

@@ -1 +1 @@
-__version__ = "0.56.0"
+__version__ = "0.58.0"

github_backup/github_backup.py

@@ -12,6 +12,7 @@ import json
 import logging
 import os
 import platform
+import random
 import re
 import select
 import socket
@@ -19,6 +20,7 @@ import ssl
 import subprocess
 import sys
 import time
+from collections.abc import Generator
 from datetime import datetime
 from http.client import IncompleteRead
 from urllib.error import HTTPError, URLError
@@ -74,6 +76,9 @@ else:
                 "  3. Debian/Ubuntu: apt-get install ca-certificates\n\n"
             )
 
+# Retry configuration
+MAX_RETRIES = 5
+
 
 def logging_subprocess(
     popenargs, stdout_log_level=logging.DEBUG, stderr_log_level=logging.ERROR, **kwargs
@@ -440,6 +445,12 @@ def parse_args(args=None):
         dest="include_assets",
         help="include assets alongside release information; only applies if including releases",
     )
+    parser.add_argument(
+        "--skip-assets-on",
+        dest="skip_assets_on",
+        nargs="*",
+        help="skip asset downloads for these repositories",
+    )
     parser.add_argument(
         "--attachments",
         action="store_true",
@@ -561,7 +572,7 @@ def get_github_host(args):
 
 
 def read_file_contents(file_uri):
-    return open(file_uri[len(FILE_URI_PREFIX):], "rt").readline().strip()
+    return open(file_uri[len(FILE_URI_PREFIX) :], "rt").readline().strip()
 
 
 def get_github_repo_url(args, repository):
@@ -597,175 +608,181 @@ def get_github_repo_url(args, repository):
     return repo_url
 
 
-def retrieve_data_gen(args, template, query_args=None, single_request=False):
-    auth = get_auth(args, encode=not args.as_app)
-    query_args = get_query_args(query_args)
-    per_page = 100
-    next_url = None
+def calculate_retry_delay(attempt, headers):
+    """Calculate delay before next retry with exponential backoff."""
+    # Respect retry-after header if present
+    if retry_after := headers.get("retry-after"):
+        return int(retry_after)
 
-    while True:
-        if single_request:
-            request_per_page = None
-        else:
-            request_per_page = per_page
+    # Respect rate limit reset time
+    if int(headers.get("x-ratelimit-remaining", 1)) < 1:
+        reset_time = int(headers.get("x-ratelimit-reset", 0))
+        return max(10, reset_time - calendar.timegm(time.gmtime()))
 
-        request = _construct_request(
-            request_per_page,
-            query_args,
-            next_url or template,
-            auth,
-            as_app=args.as_app,
-            fine=True if args.token_fine is not None else False,
-        )  # noqa
-        r, errors = _get_response(request, auth, next_url or template)
+    # Exponential backoff with jitter for server errors (1s base, 120s max)
+    delay = min(1.0 * (2**attempt), 120.0)
+    return delay + random.uniform(0, delay * 0.1)
 
-        status_code = int(r.getcode())
 
-        # Handle DMCA takedown (HTTP 451) - raise exception to skip entire repository
-        if status_code == 451:
-            dmca_url = None
-            try:
-                response_data = json.loads(r.read().decode("utf-8"))
-                dmca_url = response_data.get("block", {}).get("html_url")
-            except Exception:
-                pass
-            raise RepositoryUnavailableError(
-                "Repository unavailable due to legal reasons (HTTP 451)",
-                dmca_url=dmca_url
-            )
+def retrieve_data(args, template, query_args=None, paginated=True):
+    """
+    Fetch the data from GitHub API.
 
-        # Check if we got correct data
-        try:
-            response = json.loads(r.read().decode("utf-8"))
-        except IncompleteRead:
-            logger.warning("Incomplete read error detected")
-            read_error = True
-        except json.decoder.JSONDecodeError:
-            logger.warning("JSON decode error detected")
-            read_error = True
-        except TimeoutError:
-            logger.warning("Tiemout error detected")
-            read_error = True
-        else:
-            read_error = False
+    Handle both single requests and pagination with yield of individual dicts.
+    Handles throttling, retries, read errors, and DMCA takedowns.
+    """
+    query_args = query_args or {}
+    auth = get_auth(args, encode=not args.as_app)
+    per_page = 100
 
-        # be gentle with API request limit and throttle requests if remaining requests getting low
-        limit_remaining = int(r.headers.get("x-ratelimit-remaining", 0))
-        if args.throttle_limit and limit_remaining <= args.throttle_limit:
-            logger.info(
-                "API request limit hit: {} requests left, pausing further requests for {}s".format(
-                    limit_remaining, args.throttle_pause
+    def _extract_next_page_url(link_header):
+        for link in link_header.split(","):
+            if 'rel="next"' in link:
+                return link[link.find("<") + 1:link.find(">")]
+        return None
+
+    def fetch_all() -> Generator[dict, None, None]:
+        next_url = None
+
+        while True:
+            # FIRST: Fetch response
+
+            for attempt in range(MAX_RETRIES):
+                request = _construct_request(
+                    per_page=per_page if paginated else None,
+                    query_args=query_args,
+                    template=next_url or template,
+                    auth=auth,
+                    as_app=args.as_app,
+                    fine=args.token_fine is not None,
+                )
+                http_response = make_request_with_retry(request, auth)
+
+                match http_response.getcode():
+                    case 200:
+                        # Success - Parse JSON response
+                        try:
+                            response = json.loads(http_response.read().decode("utf-8"))
+                            break  # Exit retry loop and handle the data returned
+                        except (
+                            IncompleteRead,
+                            json.decoder.JSONDecodeError,
+                            TimeoutError,
+                        ) as e:
+                            logger.warning(f"{type(e).__name__} reading response")
+                            if attempt < MAX_RETRIES - 1:
+                                delay = calculate_retry_delay(attempt, {})
+                                logger.warning(
+                                    f"Retrying in {delay:.1f}s (attempt {attempt + 1}/{MAX_RETRIES})"
+                                )
+                                time.sleep(delay)
+                            continue  # Next retry attempt
+
+                    case 451:
+                        # DMCA takedown - extract URL if available, then raise
+                        dmca_url = None
+                        try:
+                            response_data = json.loads(
+                                http_response.read().decode("utf-8")
+                            )
+                            dmca_url = response_data.get("block", {}).get("html_url")
+                        except Exception:
+                            pass
+                        raise RepositoryUnavailableError(
+                            "Repository unavailable due to legal reasons (HTTP 451)",
+                            dmca_url=dmca_url,
+                        )
+
+                    case _:
+                        raise Exception(
+                            f"API request returned HTTP {http_response.getcode()}: {http_response.reason}"
+                        )
+            else:
+                logger.error(
+                    f"Failed to read response after {MAX_RETRIES} attempts for {next_url or template}"
+                )
+                raise Exception(
+                    f"Failed to read response after {MAX_RETRIES} attempts for {next_url or template}"
                 )
-            )
-            time.sleep(args.throttle_pause)
-
-        retries = 0
-        while retries < 3 and (status_code == 502 or read_error):
-            logger.warning("API request failed. Retrying in 5 seconds")
-            retries += 1
-            time.sleep(5)
-            request = _construct_request(
-                request_per_page,
-                query_args,
-                next_url or template,
-                auth,
-                as_app=args.as_app,
-                fine=True if args.token_fine is not None else False,
-            )  # noqa
-            r, errors = _get_response(request, auth, next_url or template)
-
-            status_code = int(r.getcode())
-            try:
-                response = json.loads(r.read().decode("utf-8"))
-                read_error = False
-            except IncompleteRead:
-                logger.warning("Incomplete read error detected")
-                read_error = True
-            except json.decoder.JSONDecodeError:
-                logger.warning("JSON decode error detected")
-                read_error = True
-            except TimeoutError:
-                logger.warning("Tiemout error detected")
-                read_error = True
-
-        if status_code != 200:
-            template = "API request returned HTTP {0}: {1}"
-            errors.append(template.format(status_code, r.reason))
-            raise Exception(", ".join(errors))
-
-        if read_error:
-            template = "API request problem reading response for {0}"
-            errors.append(template.format(request))
-            raise Exception(", ".join(errors))
-
-        if len(errors) == 0:
-            if type(response) is list:
-                for resp in response:
-                    yield resp
-                # Parse Link header for next page URL (cursor-based pagination)
-                link_header = r.headers.get("Link", "")
-                next_url = None
-                if link_header:
-                    # Parse Link header: <https://api.github.com/...?per_page=100&after=cursor>; rel="next"
-                    for link in link_header.split(","):
-                        if 'rel="next"' in link:
-                            next_url = link[link.find("<") + 1:link.find(">")]
-                            break
-                if not next_url:
-                    break
-            elif type(response) is dict and single_request:
-                yield response
 
-        if len(errors) > 0:
-            raise Exception(", ".join(errors))
+            # SECOND: Process and paginate
 
-        if single_request:
-            break
+            # Pause before next request if rate limit is low
+            if (
+                remaining := int(http_response.headers.get("x-ratelimit-remaining", 0))
+            ) <= (args.throttle_limit or 0):
+                if args.throttle_limit:
+                    logger.info(
+                        f"Throttling: {remaining} requests left, pausing {args.throttle_pause}s"
+                    )
+                    time.sleep(args.throttle_pause)
 
+            # Yield results
+            if isinstance(response, list):
+                yield from response
+            elif isinstance(response, dict):
+                yield response
 
-def retrieve_data(args, template, query_args=None, single_request=False):
-    return list(retrieve_data_gen(args, template, query_args, single_request))
+            # Check for more pages
+            if not paginated or not (
+                next_url := _extract_next_page_url(
+                    http_response.headers.get("Link", "")
+                )
+            ):
+                break  # No more data
 
+    return list(fetch_all())
 
-def get_query_args(query_args=None):
-    if not query_args:
-        query_args = {}
-    return query_args
 
+def make_request_with_retry(request, auth):
+    """Make HTTP request with automatic retry for transient errors."""
 
-def _get_response(request, auth, template):
-    retry_timeout = 3
-    errors = []
-    # We'll make requests in a loop so we can
-    # delay and retry in the case of rate-limiting
-    while True:
-        should_continue = False
+    def is_retryable_status(status_code, headers):
+        # Server errors are always retryable
+        if status_code in (500, 502, 503, 504):
+            return True
+        # Rate limit (403/429) is retryable if limit exhausted
+        if status_code in (403, 429):
+            return int(headers.get("x-ratelimit-remaining", 1)) < 1
+        return False
+
+    for attempt in range(MAX_RETRIES):
         try:
-            r = urlopen(request, context=https_ctx)
+            return urlopen(request, context=https_ctx)
+
         except HTTPError as exc:
-            errors, should_continue = _request_http_error(exc, auth, errors)  # noqa
-            r = exc
-        except URLError as e:
-            logger.warning(e.reason)
-            should_continue, retry_timeout = _request_url_error(template, retry_timeout)
-            if not should_continue:
-                raise
-        except socket.error as e:
-            logger.warning(e.strerror)
-            should_continue, retry_timeout = _request_url_error(template, retry_timeout)
-            if not should_continue:
+            # HTTPError can be used as a response-like object
+            if not is_retryable_status(exc.code, exc.headers):
+                raise  # Non-retryable error
+
+            if attempt >= MAX_RETRIES - 1:
+                logger.error(f"HTTP {exc.code} failed after {MAX_RETRIES} attempts")
                 raise
 
-        if should_continue:
-            continue
+            delay = calculate_retry_delay(attempt, exc.headers)
+            logger.warning(
+                f"HTTP {exc.code}, retrying in {delay:.1f}s "
+                f"(attempt {attempt + 1}/{MAX_RETRIES})"
+            )
+            if auth is None and exc.code in (403, 429):
+                logger.info("Hint: Authenticate to raise your GitHub rate limit")
+            time.sleep(delay)
 
-        break
-    return r, errors
+        except (URLError, socket.error) as e:
+            if attempt >= MAX_RETRIES - 1:
+                logger.error(f"Connection error failed after {MAX_RETRIES} attempts: {e}")
+                raise
+            delay = calculate_retry_delay(attempt, {})
+            logger.warning(
+                f"Connection error: {e}, retrying in {delay:.1f}s "
+                f"(attempt {attempt + 1}/{MAX_RETRIES})"
+            )
+            time.sleep(delay)
 
+    raise Exception(f"Request failed after {MAX_RETRIES} attempts")  # pragma: no cover
 
-def _construct_request(
-    per_page, query_args, template, auth, as_app=None, fine=False
-):
+
+def _construct_request(per_page, query_args, template, auth, as_app=None, fine=False):
     # If template is already a full URL with query params (from Link header), use it directly
     if "?" in template and template.startswith("http"):
         request_url = template
@@ -796,9 +813,6 @@ def _construct_request(
         else:
             auth = auth.encode("ascii")
             request.add_header("Authorization", "token ".encode("ascii") + auth)
-            request.add_header(
-                "Accept", "application/vnd.github.machine-man-preview+json"
-            )
 
     log_url = template if "?" not in template else template.split("?")[0]
     if querystring:
@@ -807,52 +821,6 @@ def _construct_request(
     return request
 
 
-def _request_http_error(exc, auth, errors):
-    # HTTPError behaves like a Response so we can
-    # check the status code and headers to see exactly
-    # what failed.
-
-    should_continue = False
-    headers = exc.headers
-    limit_remaining = int(headers.get("x-ratelimit-remaining", 0))
-
-    if exc.code == 403 and limit_remaining < 1:
-        # The X-RateLimit-Reset header includes a
-        # timestamp telling us when the limit will reset
-        # so we can calculate how long to wait rather
-        # than inefficiently polling:
-        gm_now = calendar.timegm(time.gmtime())
-        reset = int(headers.get("x-ratelimit-reset", 0)) or gm_now
-        # We'll never sleep for less than 10 seconds:
-        delta = max(10, reset - gm_now)
-
-        limit = headers.get("x-ratelimit-limit")
-        logger.warning(
-            "Exceeded rate limit of {} requests; waiting {} seconds to reset".format(
-                limit, delta
-            )
-        )  # noqa
-
-        if auth is None:
-            logger.info("Hint: Authenticate to raise your GitHub rate limit")
-
-        time.sleep(delta)
-        should_continue = True
-    return errors, should_continue
-
-
-def _request_url_error(template, retry_timeout):
-    # In case of a connection timing out, we can retry a few time
-    # But we won't crash and not back-up the rest now
-    logger.info("'{}' timed out".format(template))
-    retry_timeout -= 1
-
-    if retry_timeout >= 0:
-        return True, retry_timeout
-
-    raise Exception("'{}' timed out to much, skipping!".format(template))
-
-
 class S3HTTPRedirectHandler(HTTPRedirectHandler):
     """
     A subclassed redirect handler for downloading Github assets from S3.
@@ -1480,9 +1448,11 @@ def download_attachments(
         manifest = {
             "issue_number": number,
             "issue_type": item_type,
-            "repository": f"{args.user}/{args.repository}"
-            if hasattr(args, "repository") and args.repository
-            else args.user,
+            "repository": (
+                f"{args.user}/{args.repository}"
+                if hasattr(args, "repository") and args.repository
+                else args.user
+            ),
             "manifest_updated_at": datetime.now(timezone.utc).isoformat(),
             "attachments": attachment_metadata_list,
         }
@@ -1500,7 +1470,7 @@ def download_attachments(
 
 def get_authenticated_user(args):
     template = "https://{0}/user".format(get_github_api_host(args))
-    data = retrieve_data(args, template, single_request=True)
+    data = retrieve_data(args, template, paginated=False)
     return data[0]
 
 
@@ -1514,7 +1484,7 @@ def check_git_lfs_install():
 
 def retrieve_repositories(args, authenticated_user):
     logger.info("Retrieving repositories")
-    single_request = False
+    paginated = True
     if args.user == authenticated_user["login"]:
         # we must use the /user/repos API to be able to access private repos
         template = "https://{0}/user/repos".format(get_github_api_host(args))
@@ -1537,18 +1507,16 @@ def retrieve_repositories(args, authenticated_user):
             repo_path = args.repository
         else:
             repo_path = "{0}/{1}".format(args.user, args.repository)
-        single_request = True
-        template = "https://{0}/repos/{1}".format(
-            get_github_api_host(args), repo_path
-        )
+        paginated = False
+        template = "https://{0}/repos/{1}".format(get_github_api_host(args), repo_path)
 
-    repos = retrieve_data(args, template, single_request=single_request)
+    repos = retrieve_data(args, template, paginated=paginated)
 
     if args.all_starred:
         starred_template = "https://{0}/users/{1}/starred".format(
             get_github_api_host(args), args.user
         )
-        starred_repos = retrieve_data(args, starred_template, single_request=False)
+        starred_repos = retrieve_data(args, starred_template)
         # flag each repo as starred for downstream processing
         for item in starred_repos:
             item.update({"is_starred": True})
@@ -1558,14 +1526,17 @@ def retrieve_repositories(args, authenticated_user):
         gists_template = "https://{0}/users/{1}/gists".format(
             get_github_api_host(args), args.user
         )
-        gists = retrieve_data(args, gists_template, single_request=False)
+        gists = retrieve_data(args, gists_template)
         # flag each repo as a gist for downstream processing
         for item in gists:
             item.update({"is_gist": True})
         repos.extend(gists)
 
     if args.include_starred_gists:
-        if not authenticated_user.get("login") or args.user.lower() != authenticated_user["login"].lower():
+        if (
+            not authenticated_user.get("login")
+            or args.user.lower() != authenticated_user["login"].lower()
+        ):
             logger.warning(
                 "Cannot retrieve starred gists for '%s'. GitHub only allows access to the authenticated user's starred gists.",
                 args.user,
@@ -1574,9 +1545,7 @@ def retrieve_repositories(args, authenticated_user):
             starred_gists_template = "https://{0}/gists/starred".format(
                 get_github_api_host(args)
             )
-            starred_gists = retrieve_data(
-                args, starred_gists_template, single_request=False
-            )
+            starred_gists = retrieve_data(args, starred_gists_template)
             # flag each repo as a starred gist for downstream processing
             for item in starred_gists:
                 item.update({"is_gist": True, "is_starred": True})
@@ -1673,9 +1642,11 @@ def backup_repositories(args, output_directory, repositories):
 
         include_gists = args.include_gists or args.include_starred_gists
         include_starred = args.all_starred and repository.get("is_starred")
-        if (args.include_repository or args.include_everything) or (
-            include_gists and repository.get("is_gist")
-        ) or include_starred:
+        if (
+            (args.include_repository or args.include_everything)
+            or (include_gists and repository.get("is_gist"))
+            or include_starred
+        ):
             repo_name = (
                 repository.get("name")
                 if not repository.get("is_gist")
@@ -1735,7 +1706,9 @@ def backup_repositories(args, output_directory, repositories):
                     include_assets=args.include_assets or args.include_everything,
                 )
         except RepositoryUnavailableError as e:
-            logger.warning(f"Repository {repository['full_name']} is unavailable (HTTP 451)")
+            logger.warning(
+                f"Repository {repository['full_name']} is unavailable (HTTP 451)"
+            )
             if e.dmca_url:
                 logger.warning(f"DMCA notice: {e.dmca_url}")
             logger.info(f"Skipping remaining resources for {repository['full_name']}")
@@ -1795,7 +1768,11 @@ def backup_issues(args, repo_cwd, repository, repos_template):
             modified = os.path.getmtime(issue_file)
             modified = datetime.fromtimestamp(modified).strftime("%Y-%m-%dT%H:%M:%SZ")
             if modified > issue["updated_at"]:
-                logger.info("Skipping issue {0} because it wasn't modified since last backup".format(number))
+                logger.info(
+                    "Skipping issue {0} because it wasn't modified since last backup".format(
+                        number
+                    )
+                )
                 continue
 
         if args.include_issue_comments or args.include_everything:
@@ -1837,14 +1814,14 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
         pull_states = ["open", "closed"]
         for pull_state in pull_states:
             query_args["state"] = pull_state
-            _pulls = retrieve_data_gen(args, _pulls_template, query_args=query_args)
+            _pulls = retrieve_data(args, _pulls_template, query_args=query_args)
             for pull in _pulls:
                 if args.since and pull["updated_at"] < args.since:
                     break
                 if not args.since or pull["updated_at"] >= args.since:
                     pulls[pull["number"]] = pull
     else:
-        _pulls = retrieve_data_gen(args, _pulls_template, query_args=query_args)
+        _pulls = retrieve_data(args, _pulls_template, query_args=query_args)
         for pull in _pulls:
             if args.since and pull["updated_at"] < args.since:
                 break
@@ -1852,7 +1829,7 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
                 pulls[pull["number"]] = retrieve_data(
                     args,
                     _pulls_template + "/{}".format(pull["number"]),
-                    single_request=True,
+                    paginated=False,
                 )[0]
 
     logger.info("Saving {0} pull requests to disk".format(len(list(pulls.keys()))))
@@ -1869,7 +1846,11 @@ def backup_pulls(args, repo_cwd, repository, repos_template):
             modified = os.path.getmtime(pull_file)
             modified = datetime.fromtimestamp(modified).strftime("%Y-%m-%dT%H:%M:%SZ")
             if modified > pull["updated_at"]:
-                logger.info("Skipping pull request {0} because it wasn't modified since last backup".format(number))
+                logger.info(
+                    "Skipping pull request {0} because it wasn't modified since last backup".format(
+                        number
+                    )
+                )
                 continue
         if args.include_pull_comments or args.include_everything:
             template = comments_regular_template.format(number)
@@ -1919,9 +1900,11 @@ def backup_milestones(args, repo_cwd, repository, repos_template):
     elif written_count == 0:
         logger.info("{0} milestones unchanged, skipped write".format(total))
     else:
-        logger.info("Saved {0} of {1} milestones to disk ({2} unchanged)".format(
-            written_count, total, total - written_count
-        ))
+        logger.info(
+            "Saved {0} of {1} milestones to disk ({2} unchanged)".format(
+                written_count, total, total - written_count
+            )
+        )
 
 
 def backup_labels(args, repo_cwd, repository, repos_template):
@@ -1975,6 +1958,20 @@ def backup_releases(args, repo_cwd, repository, repos_template, include_assets=F
         )
         releases = releases[: args.number_of_latest_releases]
 
+    # Check if this repo should skip asset downloads (case-insensitive)
+    skip_assets = False
+    if include_assets:
+        repo_name = repository.get("name", "").lower()
+        repo_full_name = repository.get("full_name", "").lower()
+        skip_repos = [r.lower() for r in (args.skip_assets_on or [])]
+        skip_assets = repo_name in skip_repos or repo_full_name in skip_repos
+        if skip_assets:
+            logger.info(
+                "Skipping assets for {0} ({1} releases) due to --skip-assets-on".format(
+                    repository.get("name"), len(releases)
+                )
+            )
+
     # for each release, store it
     written_count = 0
     for release in releases:
@@ -1986,7 +1983,7 @@ def backup_releases(args, repo_cwd, repository, repos_template, include_assets=F
         if json_dump_if_changed(release, output_filepath):
             written_count += 1
 
-        if include_assets:
+        if include_assets and not skip_assets:
             assets = retrieve_data(args, release["assets_url"])
             if len(assets) > 0:
                 # give release asset files somewhere to live & download them (not including source archives)
@@ -2008,9 +2005,11 @@ def backup_releases(args, repo_cwd, repository, repos_template, include_assets=F
     elif written_count == 0:
         logger.info("{0} releases unchanged, skipped write".format(total))
     else:
-        logger.info("Saved {0} of {1} releases to disk ({2} unchanged)".format(
-            written_count, total, total - written_count
-        ))
+        logger.info(
+            "Saved {0} of {1} releases to disk ({2} unchanged)".format(
+                written_count, total, total - written_count
+            )
+        )
 
 
 def fetch_repository(
@@ -2024,9 +2023,12 @@ def fetch_repository(
 ):
     if bare_clone:
         if os.path.exists(local_dir):
-            clone_exists = subprocess.check_output(
-                ["git", "rev-parse", "--is-bare-repository"], cwd=local_dir
-            ) == b"true\n"
+            clone_exists = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "--is-bare-repository"], cwd=local_dir
+                )
+                == b"true\n"
+            )
         else:
             clone_exists = False
     else:
@@ -2047,7 +2049,9 @@ def fetch_repository(
             )
         else:
             logger.info(
-                "Skipping {0} (repository not accessible - may be empty, private, or credentials invalid)".format(name)
+                "Skipping {0} (repository not accessible - may be empty, private, or credentials invalid)".format(
+                    name
+                )
             )
         return
 

{github_backup-0.56.0.dist-info → github_backup-0.58.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-backup
-Version: 0.56.0
+Version: 0.58.0
 Summary: backup a github user or organization
 Home-page: http://github.com/josegonzalez/python-github-backup
 Author: Jose Diaz-Gonzalez
@@ -80,8 +80,8 @@ CLI Help output::
                   [--keychain-name OSX_KEYCHAIN_ITEM_NAME]
                   [--keychain-account OSX_KEYCHAIN_ITEM_ACCOUNT]
                   [--releases] [--latest-releases NUMBER_OF_LATEST_RELEASES]
-                  [--skip-prerelease] [--assets] [--attachments]
-                  [--exclude [REPOSITORY [REPOSITORY ...]]
+                  [--skip-prerelease] [--assets] [--skip-assets-on [REPO ...]]
+                  [--attachments] [--exclude [REPOSITORY [REPOSITORY ...]]
                   [--throttle-limit THROTTLE_LIMIT] [--throttle-pause THROTTLE_PAUSE]
                   USER
 
@@ -163,6 +163,9 @@ CLI Help output::
       --skip-prerelease     skip prerelease and draft versions; only applies if including releases
       --assets              include assets alongside release information; only
                             applies if including releases
+      --skip-assets-on [REPO ...]
+                            skip asset downloads for these repositories (e.g.
+                            --skip-assets-on repo1 owner/repo2)
       --attachments         download user-attachments from issues and pull requests
                             to issues/attachments/{issue_number}/ and
                             pulls/attachments/{pull_number}/ directories
@@ -204,6 +207,37 @@ Customise the permissions for your use case, but for a personal account full bac
 **Repository permissions**: Read access to contents, issues, metadata, pull requests, and webhooks.
 
 
+GitHub Apps
+~~~~~~~~~~~
+
+GitHub Apps are ideal for organization backups in CI/CD. Tokens are scoped to specific repositories and expire after 1 hour.
+
+**One-time setup:**
+
+1. Create a GitHub App at *Settings -> Developer Settings -> GitHub Apps -> New GitHub App*
+2. Set a name and homepage URL (can be any URL)
+3. Uncheck "Webhook > Active" (not needed for backups)
+4. Set permissions (same as fine-grained tokens above)
+5. Click "Create GitHub App", then note the **App ID** shown on the next page
+6. Under "Private keys", click "Generate a private key" and save the downloaded file
+7. Go to *Install App* in your app's settings
+8. Select the account/organization and which repositories to back up
+
+**CI/CD usage with GitHub Actions:**
+
+Store the App ID as a repository variable and the private key contents as a secret, then use ``actions/create-github-app-token``::
+
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ vars.APP_ID }}
+        private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+    - run: github-backup myorg -t ${{ steps.app-token.outputs.token }} --as-app -o ./backup --all
+
+Note: Installation tokens expire after 1 hour. For long-running backups, use a fine-grained personal access token instead.
+
+
 Prefer SSH
 ~~~~~~~~~~
 
@@ -391,6 +425,9 @@ Debug an error/block or incomplete backup into a temporary directory. Omit "incr
 
     github-backup -f $FINE_ACCESS_TOKEN -o /tmp/github-backup/ -l debug -P --all-starred --starred --watched --followers --following --issues --issue-comments --issue-events --pulls --pull-comments --pull-commits --labels --milestones --repositories --wikis --releases --assets --pull-details --gists --starred-gists $GH_USER
 
+Pipe a token from stdin to avoid storing it in environment variables or command history (Unix-like systems only)::
+
+    my-secret-manager get github-token | github-backup user -t file:///dev/stdin -o /backup --repositories
 
 Restoring from Backup
 =====================

github_backup-0.58.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+github_backup/__init__.py,sha256=oIkJTCdzxBkcFHWQdIvMrmJih4tpnF1BnfoNPd1mB48,23
+github_backup/__main__.py,sha256=3yorCiC63maaxbjdtaeAs-G-yAAxKSO3mprhGfa1Fho,271
+github_backup/cli.py,sha256=zMUU0pTnh9KPqv8K--KNpUNf-yaA1qWeI6AdC1KVrn8,2361
+github_backup/github_backup.py,sha256=Q3EcCwO7X8v5MPdWilx0zsJa8FLUINzSI8bjHw08O50,81287
+github_backup-0.58.0.dist-info/licenses/LICENSE.txt,sha256=ML-pLyn1qtAKo_DHMcQ8-p7k3f8cp-IR-mf5B49R2rk,1085
+github_backup-0.58.0.dist-info/METADATA,sha256=wYRqf6V7hjtir_td4uYuK296O5KHeqpCPGhsr-ndnK8,25921
+github_backup-0.58.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+github_backup-0.58.0.dist-info/entry_points.txt,sha256=cLPKK7MqC77QVb6HnT2mnyL_f-ciavJG_Y9vVHlCF68,57
+github_backup-0.58.0.dist-info/top_level.txt,sha256=Za6fKRAlxZ0b3ZBH_osPqklLe14LetdNAkvAQANT2AA,14
+github_backup-0.58.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+github_backup-0.58.0.dist-info/RECORD,,

github_backup-0.56.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-github_backup/__init__.py,sha256=pLF99dIRilisWyZd9CliPPWqIlV81Xy8XtGEMuThTaM,23
-github_backup/__main__.py,sha256=3yorCiC63maaxbjdtaeAs-G-yAAxKSO3mprhGfa1Fho,271
-github_backup/cli.py,sha256=zMUU0pTnh9KPqv8K--KNpUNf-yaA1qWeI6AdC1KVrn8,2361
-github_backup/github_backup.py,sha256=wlVrA50q5iP8BbJ_6WIIMEP7MKl_B3cKm2zvEtNYMS4,80777
-github_backup-0.56.0.dist-info/licenses/LICENSE.txt,sha256=ML-pLyn1qtAKo_DHMcQ8-p7k3f8cp-IR-mf5B49R2rk,1085
-github_backup-0.56.0.dist-info/METADATA,sha256=0N-CqtE9r3amkSHGkrgR3YeG7wylthaM0Q2RDct5vbc,24230
-github_backup-0.56.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-github_backup-0.56.0.dist-info/entry_points.txt,sha256=cLPKK7MqC77QVb6HnT2mnyL_f-ciavJG_Y9vVHlCF68,57
-github_backup-0.56.0.dist-info/top_level.txt,sha256=Za6fKRAlxZ0b3ZBH_osPqklLe14LetdNAkvAQANT2AA,14
-github_backup-0.56.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-github_backup-0.56.0.dist-info/RECORD,,