빠른 흐름
text
1. issue, PR, discussion comment 입력창에 파일을 drag and drop
2. GitHub가 Markdown 링크나 이미지 문법을 삽입
3. alt text와 설명을 사람이 읽을 수 있게 수정
4. 공개 저장소라면 접근 권한과 민감 정보 여부 확인
5. 장기 문서라면 저장소 파일로 옮길지 판단md
[debug-log.txt](https://github.com/user-attachments/files/example/debug-log.txt)첨부 기준
GitHub comment 입력창에 이미지를 끌어 놓으면 이미지 문법이, 일반 파일을 올리면 링크 문법이 삽입됩니다. 이 문법은 편리하지만, 생성된 URL이 저장소 안의 상대 경로가 아니라 GitHub가 관리하는 첨부 URL이라는 점을 구분해야 합니다.
이미지는 삽입 직후 alt text를 고쳐야 합니다. image나 파일명 그대로 두면 스크린 리더와 검색 맥락에 도움이 되지 않습니다.
md
<!-- 좋지 않음 -->
<!-- 더 나음 -->
일회성 디버깅 자료는 첨부 파일로 충분합니다. 반면 README, 릴리스 노트, 기술 문서에서 오래 유지해야 하는 이미지는 저장소의 docs/images/나 assets 경로에 두고 상대 링크로 관리하는 편이 추적과 리뷰에 유리합니다.
선택 기준
| 상황 | 선택 |
|---|---|
| PR 리뷰 중 임시 스크린샷 | comment 첨부 |
| 재현 로그 공유 | 첨부 파일 링크 |
| README에 오래 유지할 이미지 | 저장소 assets 경로 |
| 민감 정보가 섞인 파일 | 첨부 전 제거 또는 비공개 채널 |
| 공개 저장소 이슈 | 누구나 볼 수 있는 첨부인지 확인 |
| 문서 이식성 필요 | 상대 경로 이미지 우선 |
첨부 URL은 GitHub 문맥에서는 편하지만 문서 이동성은 낮습니다. 정적 사이트나 PDF로 옮길 문서는 첨부 URL보다 저장소에 포함된 파일을 기준으로 링크를 잡는 편이 안정적입니다.
주의할 점
공개 저장소에 업로드한 첨부 파일은 인증 없이 접근될 수 있습니다. 스크린샷, 로그, HAR 파일에는 token, email, 내부 URL, 고객 정보가 섞이기 쉬우므로 업로드 전에 반드시 제거해야 합니다.
첨부 파일은 Git 이력으로 리뷰되는 파일이 아닙니다. 장기 보존이 필요한 자료라면 repository file로 추가하고 PR 리뷰를 받는 방식이 더 안전합니다.
참고 링크
2 sources