github-backup 0.61.0__tar.gz → 0.61.2__tar.gz

{github_backup-0.61.0 → github_backup-0.61.2}/CHANGES.rst

@@ -1,9 +1,80 @@
 Changelog
 =========
 
-0.61.0 (2026-01-12)
+0.61.2 (2026-01-19)
 -------------------
 ------------------------
+
+Fix
+~~~
+- Skip security advisories for private repos unless explicitly
+  requested. [Lukas Bestle]
+- Handle 404 errors on security advisories. [Lukas Bestle]
+
+Other
+~~~~~
+- Chore(deps): bump black in the python-packages group.
+  [dependabot[bot]]
+
+  Bumps the python-packages group with 1 update: [black](https://github.com/psf/black).
+
+
+  Updates `black` from 25.12.0 to 26.1.0
+  - [Release notes](https://github.com/psf/black/releases)
+  - [Changelog](https://github.com/psf/black/blob/main/CHANGES.md)
+  - [Commits](https://github.com/psf/black/compare/25.12.0...26.1.0)
+
+  ---
+  updated-dependencies:
+  - dependency-name: black
+    dependency-version: 26.1.0
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+    dependency-group: python-packages
+  ...
+- Docs: Explain security advisories in README. [Lukas Bestle]
+- Feat: Only make security advisory dir if successful. [Lukas Bestle]
+
+  Avoids empty directories for private repos
+
+
+0.61.1 (2026-01-13)
+-------------------
+- Refactor test fixtures to use shared create_args helper. [Rodos]
+
+  Uses the real parse_args() function to get CLI defaults, so when
+  new arguments are added they're automatically available to all tests.
+
+  Changes:
+  - Add tests/conftest.py with create_args fixture
+  - Update 8 test files to use shared fixture
+  - Remove duplicate _create_mock_args methods
+  - Remove redundant @pytest.fixture mock_args definitions
+
+  This eliminates the need to update multiple test files when
+  adding new CLI arguments.
+- Fix fine-grained PAT attachment downloads for private repos (#477)
+  [Rodos]
+
+  Fine-grained personal access tokens cannot download attachments from
+  private repositories directly due to a GitHub platform limitation.
+
+  This adds a workaround for image attachments (/assets/ URLs) using
+  GitHub's Markdown API to convert URLs to JWT-signed URLs that can be
+  downloaded without authentication.
+
+  Changes:
+  - Add get_jwt_signed_url_via_markdown_api() function
+  - Detect fine-grained token + private repo + /assets/ URL upfront
+  - Use JWT workaround for those cases, mark success with jwt_workaround flag
+  - Skip download with skipped_at when workaround fails
+  - Add startup warning when using --attachments with fine-grained tokens
+  - Document limitation in README (file attachments still fail)
+  - Add 6 unit tests for JWT workaround logic
+
+
+0.61.0 (2026-01-12)
+-------------------
 - Docs: Add missing `--retries` argument to README. [Lukas Bestle]
 - Test: Adapt tests to new argument. [Lukas Bestle]
 - Feat: Backup of repository security advisories. [Lukas Bestle]

{github_backup-0.61.0/github_backup.egg-info → github_backup-0.61.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-backup
-Version: 0.61.0
+Version: 0.61.2
 Summary: backup a github user or organization
 Home-page: http://github.com/josegonzalez/python-github-backup
 Author: Jose Diaz-Gonzalez
@@ -311,6 +311,19 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 
 **Repository filtering** for repo files/assets handles renamed and transferred repositories gracefully. URLs are included if they either match the current repository name directly, or redirect to it (e.g., ``willmcgugan/rich`` redirects to ``Textualize/rich`` after transfer).
 
+**Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+
+
+About security advisories
+-------------------------
+
+GitHub security advisories are only available in public repositories. GitHub does not provide the respective API endpoint for private repositories.
+
+Therefore the logic is implemented as follows:
+- Security advisories are included in the `--all` option.
+- If only the `--all` option was provided, backups of security advisories are skipped for private repositories.
+- If the `--security-advisories` option is provided (on its own or in addition to `--all`), a backup of security advisories is attempted for all repositories, with graceful handling if the GitHub API doesn't return any.
+
 
 Run in Docker container
 -----------------------

{github_backup-0.61.0 → github_backup-0.61.2}/README

@@ -281,6 +281,19 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 
 **Repository filtering** for repo files/assets handles renamed and transferred repositories gracefully. URLs are included if they either match the current repository name directly, or redirect to it (e.g., ``willmcgugan/rich`` redirects to ``Textualize/rich`` after transfer).
 
+**Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+
+
+About security advisories
+-------------------------
+
+GitHub security advisories are only available in public repositories. GitHub does not provide the respective API endpoint for private repositories.
+
+Therefore the logic is implemented as follows:
+- Security advisories are included in the `--all` option.
+- If only the `--all` option was provided, backups of security advisories are skipped for private repositories.
+- If the `--security-advisories` option is provided (on its own or in addition to `--all`), a backup of security advisories is attempted for all repositories, with graceful handling if the GitHub API doesn't return any.
+
 
 Run in Docker container
 -----------------------

{github_backup-0.61.0 → github_backup-0.61.2}/README.rst

@@ -281,6 +281,19 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 
 **Repository filtering** for repo files/assets handles renamed and transferred repositories gracefully. URLs are included if they either match the current repository name directly, or redirect to it (e.g., ``willmcgugan/rich`` redirects to ``Textualize/rich`` after transfer).
 
+**Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+
+
+About security advisories
+-------------------------
+
+GitHub security advisories are only available in public repositories. GitHub does not provide the respective API endpoint for private repositories.
+
+Therefore the logic is implemented as follows:
+- Security advisories are included in the `--all` option.
+- If only the `--all` option was provided, backups of security advisories are skipped for private repositories.
+- If the `--security-advisories` option is provided (on its own or in addition to `--all`), a backup of security advisories is attempted for all repositories, with graceful handling if the GitHub API doesn't return any.
+
 
 Run in Docker container
 -----------------------

github_backup-0.61.2/github_backup/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.61.2"

{github_backup-0.61.0 → github_backup-0.61.2}/github_backup/cli.py

@@ -46,6 +46,16 @@ def main():
             "Use -t/--token or -f/--token-fine to authenticate."
         )
 
+    # Issue #477: Fine-grained PATs cannot download all attachment types from
+    # private repos. Image attachments will be retried via Markdown API workaround.
+    if args.include_attachments and args.token_fine:
+        logger.warning(
+            "Using --attachments with fine-grained token. Due to GitHub platform "
+            "limitations, file attachments (PDFs, etc.) from private repos may fail. "
+            "Image attachments will be retried via workaround. For full attachment "
+            "support, use --token-classic instead."
+        )
+
     if args.quiet:
         logger.setLevel(logging.WARNING)
 

{github_backup-0.61.0 → github_backup-0.61.2}/github_backup/github_backup.py

@@ -1062,6 +1062,65 @@ def download_attachment_file(url, path, auth, as_app=False, fine=False):
     return metadata
 
 
+def get_jwt_signed_url_via_markdown_api(url, token, repo_context):
+    """Convert a user-attachments/assets URL to a JWT-signed URL via Markdown API.
+
+    GitHub's Markdown API renders image URLs and returns HTML containing
+    JWT-signed private-user-images.githubusercontent.com URLs that work
+    without token authentication.
+
+    This is a workaround for issue #477 where fine-grained PATs cannot
+    download user-attachments URLs from private repos directly.
+
+    Limitations:
+    - Only works for /assets/ URLs (images)
+    - Does NOT work for /files/ URLs (PDFs, text files, etc.)
+    - JWT URLs expire after ~5 minutes
+
+    Args:
+        url: The github.com/user-attachments/assets/UUID URL
+        token: Raw fine-grained PAT (github_pat_...)
+        repo_context: Repository context as "owner/repo"
+
+    Returns:
+        str: JWT-signed URL from private-user-images.githubusercontent.com
+        None: If conversion fails
+    """
+
+    try:
+        payload = json.dumps(
+            {"text": f"![img]({url})", "mode": "gfm", "context": repo_context}
+        ).encode("utf-8")
+
+        request = Request("https://api.github.com/markdown", data=payload, method="POST")
+        request.add_header("Authorization", f"token {token}")
+        request.add_header("Content-Type", "application/json")
+        request.add_header("Accept", "application/vnd.github+json")
+
+        html = urlopen(request, timeout=30).read().decode("utf-8")
+
+        # Parse JWT-signed URL from HTML response
+        # Format: <img src="https://private-user-images.githubusercontent.com/...?jwt=..." ...>
+        if match := re.search(
+            r'src="(https://private-user-images\.githubusercontent\.com/[^"]+)"', html
+        ):
+            jwt_url = match.group(1)
+            logger.debug("Converted attachment URL to JWT-signed URL via Markdown API")
+            return jwt_url
+
+        logger.debug("Markdown API response did not contain JWT-signed URL")
+        return None
+
+    except HTTPError as e:
+        logger.debug(
+            "Markdown API request failed with HTTP {0}: {1}".format(e.code, e.reason)
+        )
+        return None
+    except Exception as e:
+        logger.debug("Markdown API request failed: {0}".format(str(e)))
+        return None
+
+
 def extract_attachment_urls(item_data, issue_number=None, repository_full_name=None):
     """Extract GitHub-hosted attachment URLs from issue/PR body and comments.
 
@@ -1415,15 +1474,46 @@ def download_attachments(
         filename = get_attachment_filename(url)
         filepath = os.path.join(attachments_dir, filename)
 
-        # Download and get metadata
-        metadata = download_attachment_file(
-            url,
-            filepath,
-            get_auth(args, encode=not args.as_app),
-            as_app=args.as_app,
-            fine=args.token_fine is not None,
+        # Issue #477: Fine-grained PATs cannot download user-attachments/assets
+        # from private repos directly (404). Use Markdown API workaround to get
+        # a JWT-signed URL. Only works for /assets/ (images), not /files/.
+        needs_jwt = (
+            args.token_fine is not None
+            and repository.get("private", False)
+            and "github.com/user-attachments/assets/" in url
         )
 
+        if not needs_jwt:
+            # NORMAL download path
+            metadata = download_attachment_file(
+                url,
+                filepath,
+                get_auth(args, encode=not args.as_app),
+                as_app=args.as_app,
+                fine=args.token_fine is not None,
+            )
+        elif jwt_url := get_jwt_signed_url_via_markdown_api(
+            url, args.token_fine, repository["full_name"]
+        ):
+            # JWT needed and extracted, download via JWT
+            metadata = download_attachment_file(
+                jwt_url, filepath, auth=None, as_app=False, fine=False
+            )
+            metadata["url"] = url  # Apply back the original URL
+            metadata["jwt_workaround"] = True
+        else:
+            # Markdown API workaround failed - skip download we know will fail
+            metadata = {
+                "url": url,
+                "success": False,
+                "skipped_at": datetime.now(timezone.utc).isoformat(),
+                "error": "Fine-grained token cannot download private repo attachments. "
+                "Markdown API workaround failed. Use --token-classic instead.",
+            }
+            logger.warning(
+                "Skipping attachment {0}: {1}".format(url, metadata["error"])
+            )
+
         # If download succeeded but we got an extension from Content-Disposition,
         # we may need to rename the file to add the extension
         if metadata["success"] and metadata.get("original_filename"):
@@ -1724,7 +1814,7 @@ def backup_repositories(args, output_directory, repositories):
             if args.include_milestones or args.include_everything:
                 backup_milestones(args, repo_cwd, repository, repos_template)
 
-            if args.include_security_advisories or args.include_everything:
+            if args.include_security_advisories or (args.include_everything and not repository["Private"]):
                 backup_security_advisories(args, repo_cwd, repository, repos_template)
 
             if args.include_labels or args.include_everything:
@@ -1949,11 +2039,20 @@ def backup_security_advisories(args, repo_cwd, repository, repos_template):
         return
 
     logger.info("Retrieving {0} security advisories".format(repository["full_name"]))
-    mkdir_p(repo_cwd, advisory_cwd)
 
-    template = "{0}/{1}/security-advisories".format(repos_template, repository["full_name"])
+    template = "{0}/{1}/security-advisories".format(
+        repos_template, repository["full_name"]
+    )
 
-    _advisories = retrieve_data(args, template)
+    try:
+        _advisories = retrieve_data(args, template)
+    except Exception as e:
+        if "404" in str(e):
+            logger.info("Security advisories are not available for this repository, skipping")
+            return
+        raise
+
+    mkdir_p(repo_cwd, advisory_cwd)
 
     advisories = {}
     for advisory in _advisories:

{github_backup-0.61.0 → github_backup-0.61.2/github_backup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-backup
-Version: 0.61.0
+Version: 0.61.2
 Summary: backup a github user or organization
 Home-page: http://github.com/josegonzalez/python-github-backup
 Author: Jose Diaz-Gonzalez
@@ -311,6 +311,19 @@ The tool automatically extracts file extensions from HTTP headers to ensure file
 
 **Repository filtering** for repo files/assets handles renamed and transferred repositories gracefully. URLs are included if they either match the current repository name directly, or redirect to it (e.g., ``willmcgugan/rich`` redirects to ``Textualize/rich`` after transfer).
 
+**Fine-grained token limitation:** Due to a GitHub platform limitation, fine-grained personal access tokens (``github_pat_...``) cannot download attachments from private repositories directly. This affects both ``/assets/`` (images) and ``/files/`` (documents) URLs. The tool implements a workaround for image attachments using GitHub's Markdown API, which converts URLs to temporary JWT-signed URLs that can be downloaded. However, this workaround only works for images - document attachments (PDFs, text files, etc.) will fail with 404 errors when using fine-grained tokens on private repos. For full attachment support on private repositories, use a classic token (``-t``) instead of a fine-grained token (``-f``). See `#477 <https://github.com/josegonzalez/python-github-backup/issues/477>`_ for details.
+
+
+About security advisories
+-------------------------
+
+GitHub security advisories are only available in public repositories. GitHub does not provide the respective API endpoint for private repositories.
+
+Therefore the logic is implemented as follows:
+- Security advisories are included in the `--all` option.
+- If only the `--all` option was provided, backups of security advisories are skipped for private repositories.
+- If the `--security-advisories` option is provided (on its own or in addition to `--all`), a backup of security advisories is attempted for all repositories, with graceful handling if the GitHub API doesn't return any.
+
 
 Run in Docker container
 -----------------------

{github_backup-0.61.0 → github_backup-0.61.2}/release-requirements.txt

@@ -1,6 +1,6 @@
 # Linting & Formatting
 autopep8==2.3.2
-black==25.12.0
+black==26.1.0
 flake8==7.3.0
 
 # Testing

{github_backup-0.61.0 → github_backup-0.61.2}/tests/test_all_starred.py

@@ -1,7 +1,7 @@
 """Tests for --all-starred flag behavior (issue #225)."""
 
 import pytest
-from unittest.mock import Mock, patch
+from unittest.mock import patch
 
 from github_backup import github_backup
 
@@ -12,58 +12,14 @@ class TestAllStarredCloning:
     Issue #225: --all-starred should clone starred repos without requiring --repositories.
     """
 
-    def _create_mock_args(self, **overrides):
-        """Create a mock args object with sensible defaults."""
-        args = Mock()
-        args.user = "testuser"
-        args.output_directory = "/tmp/backup"
-        args.include_repository = False
-        args.include_everything = False
-        args.include_gists = False
-        args.include_starred_gists = False
-        args.all_starred = False
-        args.skip_existing = False
-        args.bare_clone = False
-        args.lfs_clone = False
-        args.no_prune = False
-        args.include_wiki = False
-        args.include_issues = False
-        args.include_issue_comments = False
-        args.include_issue_events = False
-        args.include_pulls = False
-        args.include_pull_comments = False
-        args.include_pull_commits = False
-        args.include_pull_details = False
-        args.include_labels = False
-        args.include_hooks = False
-        args.include_milestones = False
-        args.include_security_advisories = False
-        args.include_releases = False
-        args.include_assets = False
-        args.include_attachments = False
-        args.incremental = False
-        args.incremental_by_files = False
-        args.github_host = None
-        args.prefer_ssh = False
-        args.token_classic = None
-        args.token_fine = None
-        args.as_app = False
-        args.osx_keychain_item_name = None
-        args.osx_keychain_item_account = None
-
-        for key, value in overrides.items():
-            setattr(args, key, value)
-
-        return args
-
     @patch('github_backup.github_backup.fetch_repository')
     @patch('github_backup.github_backup.get_github_repo_url')
-    def test_all_starred_clones_without_repositories_flag(self, mock_get_url, mock_fetch):
+    def test_all_starred_clones_without_repositories_flag(self, mock_get_url, mock_fetch, create_args):
         """--all-starred should clone starred repos without --repositories flag.
 
         This is the core fix for issue #225.
         """
-        args = self._create_mock_args(all_starred=True)
+        args = create_args(all_starred=True)
         mock_get_url.return_value = "https://github.com/otheruser/awesome-project.git"
 
         # A starred repository (is_starred flag set by retrieve_repositories)
@@ -88,9 +44,9 @@ class TestAllStarredCloning:
 
     @patch('github_backup.github_backup.fetch_repository')
     @patch('github_backup.github_backup.get_github_repo_url')
-    def test_starred_repo_not_cloned_without_all_starred_flag(self, mock_get_url, mock_fetch):
+    def test_starred_repo_not_cloned_without_all_starred_flag(self, mock_get_url, mock_fetch, create_args):
         """Starred repos should NOT be cloned if --all-starred is not set."""
-        args = self._create_mock_args(all_starred=False)
+        args = create_args(all_starred=False)
         mock_get_url.return_value = "https://github.com/otheruser/awesome-project.git"
 
         starred_repo = {
@@ -111,9 +67,9 @@ class TestAllStarredCloning:
 
     @patch('github_backup.github_backup.fetch_repository')
     @patch('github_backup.github_backup.get_github_repo_url')
-    def test_non_starred_repo_not_cloned_with_only_all_starred(self, mock_get_url, mock_fetch):
+    def test_non_starred_repo_not_cloned_with_only_all_starred(self, mock_get_url, mock_fetch, create_args):
         """Non-starred repos should NOT be cloned when only --all-starred is set."""
-        args = self._create_mock_args(all_starred=True)
+        args = create_args(all_starred=True)
         mock_get_url.return_value = "https://github.com/testuser/my-project.git"
 
         # A regular (non-starred) repository
@@ -135,9 +91,9 @@ class TestAllStarredCloning:
 
     @patch('github_backup.github_backup.fetch_repository')
     @patch('github_backup.github_backup.get_github_repo_url')
-    def test_repositories_flag_still_works(self, mock_get_url, mock_fetch):
+    def test_repositories_flag_still_works(self, mock_get_url, mock_fetch, create_args):
         """--repositories flag should still clone repos as before."""
-        args = self._create_mock_args(include_repository=True)
+        args = create_args(include_repository=True)
         mock_get_url.return_value = "https://github.com/testuser/my-project.git"
 
         regular_repo = {

{github_backup-0.61.0 → github_backup-0.61.2}/tests/test_attachments.py

@@ -4,7 +4,7 @@ import json
 import os
 import tempfile
 from pathlib import Path
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
 
 import pytest
 
@@ -12,22 +12,13 @@ from github_backup import github_backup
 
 
 @pytest.fixture
-def attachment_test_setup(tmp_path):
+def attachment_test_setup(tmp_path, create_args):
     """Fixture providing setup and helper for attachment download tests."""
-    from unittest.mock import patch
-
     issue_cwd = tmp_path / "issues"
     issue_cwd.mkdir()
 
-    # Mock args
-    args = Mock()
-    args.as_app = False
-    args.token_fine = None
-    args.token_classic = None
-    args.osx_keychain_item_name = None
-    args.osx_keychain_item_account = None
-    args.user = "testuser"
-    args.repository = "testrepo"
+    # Create args using shared fixture
+    args = create_args(user="testuser", repository="testrepo")
 
     repository = {"full_name": "testuser/testrepo"}
 
@@ -349,3 +340,146 @@ class TestManifestDuplicatePrevention:
             downloaded_urls[0]
             == "https://github.com/user-attachments/assets/unavailable"
         )
+
+
+class TestJWTWorkaround:
+    """Test JWT workaround for fine-grained tokens on private repos (issue #477)."""
+
+    def test_markdown_api_extracts_jwt_url(self):
+        """Markdown API response with JWT URL is extracted correctly."""
+        html_response = (
+            '<p><a href="https://private-user-images.githubusercontent.com'
+            '/123/abc.png?jwt=eyJhbGciOiJ"><img src="https://private-user-'
+            'images.githubusercontent.com/123/abc.png?jwt=eyJhbGciOiJ" '
+            'alt="img"></a></p>'
+        )
+
+        mock_response = Mock()
+        mock_response.read.return_value = html_response.encode("utf-8")
+
+        with patch("github_backup.github_backup.urlopen", return_value=mock_response):
+            result = github_backup.get_jwt_signed_url_via_markdown_api(
+                "https://github.com/user-attachments/assets/abc123",
+                "github_pat_token",
+                "owner/repo"
+            )
+
+        expected = (
+            "https://private-user-images.githubusercontent.com"
+            "/123/abc.png?jwt=eyJhbGciOiJ"
+        )
+        assert result == expected
+
+    def test_markdown_api_returns_none_on_http_error(self):
+        """HTTP errors return None."""
+        from urllib.error import HTTPError
+
+        error = HTTPError("http://test", 403, "Forbidden", {}, None)
+        with patch("github_backup.github_backup.urlopen", side_effect=error):
+            result = github_backup.get_jwt_signed_url_via_markdown_api(
+                "https://github.com/user-attachments/assets/abc123",
+                "github_pat_token",
+                "owner/repo"
+            )
+
+        assert result is None
+
+    def test_markdown_api_returns_none_when_no_jwt_url(self):
+        """Response without JWT URL returns None."""
+        mock_response = Mock()
+        mock_response.read.return_value = b"<p>No image here</p>"
+
+        with patch("github_backup.github_backup.urlopen", return_value=mock_response):
+            result = github_backup.get_jwt_signed_url_via_markdown_api(
+                "https://github.com/user-attachments/assets/abc123",
+                "github_pat_token",
+                "owner/repo"
+            )
+
+        assert result is None
+
+    def test_needs_jwt_only_for_fine_grained_private_assets(self):
+        """needs_jwt is True only for fine-grained + private + /assets/ URL."""
+        assets_url = "https://github.com/user-attachments/assets/abc123"
+        files_url = "https://github.com/user-attachments/files/123/doc.pdf"
+        token_fine = "github_pat_test"
+        private = True
+        public = False
+
+        # Fine-grained + private + assets = True
+        needs_jwt = (
+            token_fine is not None
+            and private
+            and "github.com/user-attachments/assets/" in assets_url
+        )
+        assert needs_jwt is True
+
+        # Fine-grained + private + files = False
+        needs_jwt = (
+            token_fine is not None
+            and private
+            and "github.com/user-attachments/assets/" in files_url
+        )
+        assert needs_jwt is False
+
+        # Fine-grained + public + assets = False
+        needs_jwt = (
+            token_fine is not None
+            and public
+            and "github.com/user-attachments/assets/" in assets_url
+        )
+        assert needs_jwt is False
+
+    def test_jwt_workaround_sets_manifest_flag(self, attachment_test_setup):
+        """Successful JWT workaround sets jwt_workaround flag in manifest."""
+        setup = attachment_test_setup
+        setup["args"].token_fine = "github_pat_test"
+        setup["repository"]["private"] = True
+
+        issue_data = {"body": "https://github.com/user-attachments/assets/abc123"}
+
+        jwt_url = "https://private-user-images.githubusercontent.com/123/abc.png?jwt=token"
+
+        with patch(
+            "github_backup.github_backup.get_jwt_signed_url_via_markdown_api",
+            return_value=jwt_url
+        ), patch(
+            "github_backup.github_backup.download_attachment_file",
+            return_value={"success": True, "http_status": 200, "url": jwt_url}
+        ):
+            github_backup.download_attachments(
+                setup["args"], setup["issue_cwd"], issue_data, 123, setup["repository"]
+            )
+
+        manifest_path = os.path.join(setup["issue_cwd"], "attachments", "123", "manifest.json")
+        with open(manifest_path) as f:
+            manifest = json.load(f)
+
+        assert manifest["attachments"][0]["jwt_workaround"] is True
+        assert manifest["attachments"][0]["url"] == "https://github.com/user-attachments/assets/abc123"
+
+    def test_jwt_workaround_failure_uses_skipped_at(self, attachment_test_setup):
+        """Failed JWT workaround uses skipped_at instead of downloaded_at."""
+        setup = attachment_test_setup
+        setup["args"].token_fine = "github_pat_test"
+        setup["repository"]["private"] = True
+
+        issue_data = {"body": "https://github.com/user-attachments/assets/abc123"}
+
+        with patch(
+            "github_backup.github_backup.get_jwt_signed_url_via_markdown_api",
+            return_value=None  # Markdown API failed
+        ):
+            github_backup.download_attachments(
+                setup["args"], setup["issue_cwd"], issue_data, 123, setup["repository"]
+            )
+
+        manifest_path = os.path.join(setup["issue_cwd"], "attachments", "123", "manifest.json")
+        with open(manifest_path) as f:
+            manifest = json.load(f)
+
+        attachment = manifest["attachments"][0]
+        assert attachment["success"] is False
+        assert "skipped_at" in attachment
+        assert "downloaded_at" not in attachment
+        assert "Use --token-classic" in attachment["error"]