마크다운 이미지가 전부 엑스박스로? 깃허브 이미지 호스팅 실패와 뼈아픈 교훈

마크다운 이미지가 전부 엑스박스로? 깃허브 이미지 호스팅 실패와 뼈아픈 교훈

안녕하세요. 파이선생 AI 자동화랩의 파이선생입니다.

최근 파이선생 AI 자동화랩의 가장 큰 목표였던 '블로그 자동 발행 파이프라인'을 만들면서, 저를 마지막까지 괴롭힌 문제가 하나 있었습니다. 바로 본문 안에 이미지를 넣는 작업이었습니다. 기술 블로그 특성상 텍스트만으로는 한계가 있어서 썸네일이나 에러 화면 캡처가 꼭 필요한데, 제 PC에서 마크다운 에디터로 글을 쓸 때는 이미지가 아주 잘 보였습니다. 그래서 파이썬 자동화 봇이 이 글을 복사해서 티스토리에 붙여넣기만 하면 당연히 이미지도 함께 올라갈 것이라고 막연하게 생각했죠.

이처럼 로컬 에디터에서 정상적으로 보이는 이미지가, 실제 블로그에 업로드된 후에는 왜 엑스박스로 출력되는지 그 원인을 하나씩 파헤쳐 보았다.

단순한 복사 붙여넣기의 처참한 결과

부푼 기대감을 안고 스크립트를 실행했습니다. 자동화 봇은 제가 짠 코드대로 로그인부터 최종 발행까지 정상적으로 움직였습니다. "결국 끝났구나!" 생각하며 발행된 블로그 링크를 눌러보았습니다. 하지만 화면을 마주한 순간 저는 크게 당황할 수밖에 없었습니다. 글과 코드는 멀쩡하게 올라갔는데, 정작 가장 중요한 설명용 이미지들이 전부 깨진 '엑스박스'로 표시되어 있었던 것입니다.

처음에는 마크다운 파일의 이미지 경로 문제라고 생각했습니다. 그래서 결코 경로를 넣어보기도 하고, 띄어쓰기를 다듬어 보기도 했습니다. 하지만 며칠간 디버깅을 해보니 문제는 문법 오류가 아니었습니다. 제 PC에 있는 이미지 파일을 카카오 서버로 물리적으로 전송하지 않았으니, 외부 독자의 브라우저에서 제 PC 경로를 읽지 못해 엑스박스가 뜨는 것은 너무나 당연한 이치였던 것이죠.

대안으로 찾은 GitHub 이미지 호스팅

물리적인 업로드 문제를 해결하기 위해, 유효한 웹 URL만 있으면 어디서든 이미지를 불러올 수 있는 외부 이미지 서버(호스팅) 방식을 고민했습니다. 그리고 개발자에게 가장 익숙하고 무료로 쓸 수 있는 깃허브(GitHub) 저장소를 활용하기로 결심했습니다.

곧바로 github_image_uploader.py라는 파이썬 모듈을 만들었습니다. 이 코드는 글을 발행하기 전에 마크다운에 첨부된 이미지들을 제 깃허브 저장소로 밀어 넣고, 업로드된 이미지의 원본 다운로드 링크(Raw URL)를 추출한 뒤, 본문 속 로컬 이미지 경로를 이 URL로 싹 바꿔주는 역할을 합니다.

GitHub API를 연동하여 이미지 호스팅을 자동화하는 실제 Python 코드 캡처본

GitHub API를 연동하여 이미지 호스팅을 자동화하는 실제 Python 코드 캡처본

작성한 코드를 통해 로컬 마크다운 파일의 경로를 성공적으로 깃허브 Raw URL로 변환했고, 이제 모든 문제가 해결된 줄 알았다.

해결된 줄 알았는데 찾아온 뜻밖의 함정

코드를 적용하고 나니 로컬 경로가 https://raw.githubusercontent.com/... 형태로 변환되면서 제 모니터에서는 티스토리 글 속 이미지가 선명하게 잘 보였습니다. 결국 해냈다는 생각에 안도했지만, 혹시나 하는 마음에 스마트폰으로 방금 올린 글을 열어본 순간 또다시 엑스박스가 저를 반겼습니다.

알고 보니 제가 이미지용으로 만든 깃허브 저장소가 '비공개(Private)'로 설정되어 있었던 것입니다. 작성자인 제 PC 브라우저에는 깃허브 로그인 정보가 남아있어서 정상적으로 이미지가 보였지만, 권한이 없는 일반 방문자나 모바일에서는 접근이 차단된 것이었죠. 제 컴퓨터에서만 멀쩡하게 보이고 외부에는 깨져 보이는, 아주 무서운 권한 설정의 함정이었습니다.

속도보다 중요한 것은 발행 전 검증입니다

이번 깃허브 이미지 호스팅 실험과 엑스박스 사태를 겪으며 뼈저리게 느낀 점이 있습니다. 자동화의 핵심은 무작정 결과물을 빠르게 쏟아내는 것이 아니라, 글이 발행된 후 외부 환경에서도 제대로 보이는지 철저하게 검증하는 과정이라는 것입니다.

앞으로 자동화 파이프라인에는 이미지 업로드 직후에 해당 URL이 외부에서도 문제없이 열리는지(HTTP 200 상태 코드 반환 여부) 코드로 미리 검사하고, 발행 전에는 미리보기 리포트를 만들어 담당자가 눈으로 직접 확인하도록 검수 구조를 추가할 계획입니다. 속도에 집착하는 공장형 봇이 아니라 단 하나의 글이라도 안정적으로 독자에게 전달되는 파이프라인. 그것이 제가 진정으로 만들고 싶은 AI 자동화입니다.

특히, 이미지 호스팅을 위해 깃허브를 활용하는 방식은 단순한 우회책을 넘어, 에셋(Asset) 관리의 일원화라는 측면에서도 큰 장점을 가집니다. 로컬 PC에 흩어져 있던 이미지 파일들을 체계적으로 관리할 수 있고, 만약 티스토리 서버에 문제가 생기더라도 이미지는 안전하게 깃허브에 보존되기 때문입니다. 다만, 이러한 장점을 누리기 위해서는 반드시 저장소 접근 권한(Public)과 원본 링크(Raw URL) 구조에 대한 정확한 이해가 선행되어야 합니다. 앞으로는 이미지뿐만 아니라 자동화에 필요한 모든 외부 리소스들의 접근 권한을 스크립트 단에서 한 번 더 체크하는 로직을 고민해 볼 것입니다.

이 글을 읽고 계신 여러분도 블로그나 웹사이트를 자동화할 때 로컬 리소스와 클라우드 리소스 간의 권한 차이를 간과하지 마시기 바랍니다. 사소한 설정 하나가 치명적인 사용자 경험 저하로 이어질 수 있으니까요. 기술의 편리함 이면에 숨겨진 함정을 파악하고 대비하는 것 역시 엔지니어의 중요한 역할입니다.