Skip to content

docs: add case study for image upload failures in private repos #1034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
konard wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs: add case study for image upload failures in private repos #1034

konard wants to merge 7 commits into from

Conversation

@konard
Copy link
Contributor

@konard konard commented Dec 29, 2025 •
edited
Loading

Summary

This PR addresses issue #1033 (image uploads not working in private repository comments) by:

  1. Adding comprehensive case study analysis - Documents the root cause and timeline of the failure
  2. Implementing enhanced system prompt guidance - Adds new "Uploading images to GitHub comments" section to all prompt files

Key Findings

  • Root Cause: raw.githubusercontent.com does not support authentication at all
  • Even authenticated users with access to the private repository cannot view images
  • Browser's HTTP requests to fetch images cannot carry GitHub authentication tokens
  • Authentication tokens included in requests are silently ignored

Technical Details

According to GitHub Community Discussion #160828:

"As far as I can tell, raw.githubusercontent.com doesn't actually support authentication at all. You can throw your personal access token in the header, but it's ignored - no rate limit headers, no feedback, nothing."

What Failed

PR comment in kogeletey/egida-test (private) referenced images like:

![Image](https://raw.githubusercontent.com/kogeletey/egida-test/branch/file.png)

These URLs return 404 for everyone - even authenticated users with repository access - because the browser making the image request cannot authenticate with raw.githubusercontent.com.

Solution Implemented

Added new "Uploading images to GitHub comments" guidance section to all prompt files:

  • src/claude.prompts.lib.mjs
  • src/agent.prompts.lib.mjs
  • src/codex.prompts.lib.mjs
  • src/opencode.prompts.lib.mjs

The guidance includes:

  1. For PUBLIC repositories: Can use raw.githubusercontent.com URLs
  2. For PRIVATE repositories: NEVER use raw.githubusercontent.com URLs - they will return 404 even for authenticated viewers. Use base64 encoding for small images.

Files Changed

  • docs/case-studies/issue-1033/README.md - Comprehensive case study with corrected analysis
  • docs/case-studies/issue-1033/logs/ - Supporting logs and data
  • src/*.prompts.lib.mjs - Added private repo image handling guidance to all 4 prompt files
  • .changeset/private-repo-image-guidance.md - Updated changeset

External References

Test Plan

  • Case study accurately describes the failure
  • Root cause analysis is backed by external sources and user feedback
  • Solutions are actionable and technically sound
  • Guidance added to all 4 prompt files for consistency
  • Prettier format check passes
  • ESLint check passes

Fixes #1033

🤖 Generated with Claude Code

@konard
Initial commit with task details
d5ee7ea 
Adding CLAUDE.md with task information for AI processing.
This file will be removed when the task is complete.

Issue: #1033
@konard konard self-assigned this Dec 29, 2025
konard and others added 2 commits December 29, 2025 20:30
@konard @claude
docs: add case study for issue #1033 - image upload failures in priva…
c165473 
…te repos

This case study analyzes why images uploaded to PR comments didn't display
in a private repository (kogeletey/egida-test) while the same approach
worked correctly in a public repository.

Key findings:
- raw.githubusercontent.com URLs require authentication for private repos
- GitHub returns 404 (not 403) for unauthenticated requests to private files
- gh gist create doesn't support binary files as a fallback
- GitHub has no REST API for uploading images to issue/PR comments

Included artifacts:
- Complete session log from the failed image upload session
- Summary of comments from both failed and successful PRs
- Timeline reconstruction and root cause analysis
- Proposed solutions including external image hosting

Fixes #1033

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@konard @claude
docs: add supporting logs for issue #1033 case study
6a36675 
This commit adds the raw data collected for the case study:
- failed-session-log.txt: Complete execution trace from the failed session
- successful-pr-comments-raw.json: Comments from successful public repo PR
- failed-pr-comments-summary.json: Summary of comments from the failing PR

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@konard konard changed the title [WIP] Uploading of images to comments didn't work docs: add case study for image upload failures in private repos Dec 29, 2025
@konard konard marked this pull request as ready for review December 29, 2025 19:30
@konard
Copy link
Contributor Author

konard commented Dec 29, 2025

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $2.691509 USD
  • Calculated by Anthropic: $2.094574 USD
  • Difference: $-0.596936 (-22.18%)
    📎 Log file uploaded as GitHub Gist (475KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard
Copy link
Contributor Author

konard commented Dec 29, 2025 •
edited
Loading

Let's do Enhanced system prompt - Add private repo guidance, double check all conclusions you have ended up with though, to make sure we really found the root cause and listed solutions are the best ones.

@konard konard marked this pull request as draft December 29, 2025 19:44
@konard
Copy link
Contributor Author

konard commented Dec 29, 2025

🤖 AI Work Session Started

Starting automated work session at 2025-12-29T19:44:09.117Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

konard and others added 2 commits December 29, 2025 20:50
@konard @claude
feat: add private repo image upload guidance to system prompts
8b977a2 
- Add new "Uploading images to GitHub comments" section to all prompt files
- Clarify that raw.githubusercontent.com URLs only work for public repos
- Provide alternative solutions for private repos (external hosting, base64, etc.)
- Note that gh gist create doesn't support binary files
- Fix Prettier formatting in case study README.md

This addresses the root cause of issue #1033 by providing guidance to the AI
agent on how to properly handle image uploads in private repositories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@konard @claude
chore: add changeset for private repo image guidance
9be3dae 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@konard konard marked this pull request as ready for review December 29, 2025 19:57
@konard
Copy link
Contributor Author

konard commented Dec 29, 2025

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard
Copy link
Contributor Author

konard commented Dec 29, 2025 

 1. External image hosting (recommended): Upload to imgbb.com, Cloudinary, or similar services that provide public URLs
         3. GitHub's user-attachments: If available through web interface automation
   - When using gh gist create for images, note that binary files are not supported - gist only accepts text files.
   - When in doubt about repository visibility, use external image hosting as it works for both public and private repositories.

These lines should be removed.

Also your analysis is wrong, because user has authentication and has access to pull request in private repository, yet images are not shown. You need to redo the analysis based on data in original issue.

@konard konard marked this pull request as draft December 29, 2025 20:04
@konard
Copy link
Contributor Author

konard commented Dec 29, 2025

🤖 AI Work Session Started

Starting automated work session at 2025-12-29T20:04:02.860Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

@konard @claude
fix: correct private repo image guidance - raw.githubusercontent.com …
f282bd6 
…doesn't support auth

- Remove incorrect external image hosting recommendations per user feedback
- Clarify that raw.githubusercontent.com does not support authentication at all
- Even authenticated users cannot view images from private repos via raw URLs
- Browser's HTTP requests to fetch images cannot carry GitHub authentication tokens
- Update case study with corrected root cause analysis
- Recommend base64 encoding as the only viable solution for private repo images

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@konard konard marked this pull request as ready for review December 29, 2025 20:12
@konard
Copy link
Contributor Author

konard commented Dec 29, 2025

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $4.879005 USD
  • Calculated by Anthropic: $3.415815 USD
  • Difference: $-1.463190 (-29.99%)
    📎 Log file uploaded as GitHub Gist (725KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard
Copy link
Contributor Author

konard commented Dec 31, 2025

Can we try https://github.com/link-foundation/gh-upload-image? Will it work?

@konard konard marked this pull request as draft December 31, 2025 10:23
@konard
Copy link
Contributor Author

konard commented Dec 31, 2025

🤖 AI Work Session Started

Starting automated work session at 2025-12-31T10:23:23.867Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

@konard
Copy link
Contributor Author

konard commented Dec 31, 2025

Investigation: gh-upload-image Tool

I investigated the gh-upload-image tool as requested.

What the Tool Does

The tool aims to upload images to GitHub using the undocumented /upload/policies/assets endpoint. This would generate URLs in the format https://github.com/user-attachments/assets/{id} - the same URLs that GitHub's web UI generates when you drag-and-drop images. These URLs work for both public and private repositories.

Test Results

I installed and tested the tool:

$ npm install github:link-foundation/gh-upload-image
$ npx gh-upload-image test-image.png -r link-assistant/hive-mind --verbose

Result: 422 Unprocessable Entity error

The API returned GitHub's "Your browser did something unexpected" error page, which indicates the endpoint is detecting that the request is not coming from an actual browser session.

Root Cause

The undocumented /upload/policies/assets endpoint likely requires:

  • Browser session cookies
  • CSRF tokens from an active session
  • Specific headers that only browsers send

The OAuth token from gh auth alone is not sufficient - the endpoint silently ignores standard authentication.

Conclusion

Currently, gh-upload-image does NOT work due to GitHub's anti-automation measures on this undocumented endpoint.

The concept is sound - if it worked, it would solve the private repository image problem perfectly since user-attachments/assets URLs work for both public and private repos. However, the implementation fails because GitHub's undocumented API requires browser session context that cannot be replicated via CLI.

Current Recommended Solutions (from existing guidance)

For now, the guidance in the system prompts remains correct:

  • PUBLIC repositories: Use raw.githubusercontent.com URLs
  • PRIVATE repositories: Use base64 encoding for small images (data URIs embedded in markdown)

If the gh-upload-image tool or a similar approach starts working in the future, we can update the guidance to recommend it.

This analysis was based on testing performed on 2025-12-31

@konard konard marked this pull request as ready for review December 31, 2025 10:30
@konard
Copy link
Contributor Author

konard commented Dec 31, 2025

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Public pricing estimate: $3.172700 USD
  • Calculated by Anthropic: $1.894910 USD
  • Difference: $-1.277789 (-40.27%)
    📎 Log file uploaded as GitHub Gist (372KB)
    🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@konard konard

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uploading of images to comments didn't work

2 participants

@konard