코드►기타

배포 커밋은 떴는데 글 주소는 404 — GitHub Pages 반영 지연을 curl 폴링으로 기다리는 법

푸시도 했고 deploy 커밋도 떴는데

며칠 전 글 10편을 푸시하고 Actions가 master에 deploy: <해시> 커밋을 만든 것까지 확인했다. 그런데 새 글 주소를 열면 404였다. 빌드가 실패한 것도 아니고 글이 빠진 것도 아니었다. 그냥 기다리면 열렸는데, 이날은 약 10분이 걸렸다. 그때 어떻게 “열렸는지”를 기계적으로 확인하게 만들었는지 정리해 둔다.

배포 흐름과 어디서 늦는가

내 블로그 구조는 이렇다.

  1. 글과 설정은 gh-pages 브랜치(소스)에 푸시한다.
  2. GitHub Actions가 Hexo를 빌드해서 결과물을 master에 올린다. 커밋 메시지는 deploy: <소스 해시>.
  3. GitHub Pages가 master의 새 커밋을 받아 사이트에 반영한다.

2번이 끝나면 master에 커밋이 보이지만, 3번은 별개 단계다. 그래서 커밋이 보인다고 사이트가 바뀐 것은 아니다. 이날 내가 겪은 404는 2번과 3번 사이의 시간차였다.

먼저 확인하는 세 가지

404를 보면 우선 빌드가 진짜로 끝났는지부터 본다.

1
2
3
cd C:/project/tuhbm.github.io
git fetch origin master
git log -1 --format='%s' origin/master

출력이 deploy: <방금 푸시한 gh-pages 해시>면 2번까지는 정상이다. 해시가 이전 것이면 아직 Actions가 도는 중이거나 실패한 것이다. 이 경우는 Actions 탭을 봐야 한다.

해시가 맞는데도 404면 3번 지연이다. 이때 할 일은 조급해하지 않고 응답 코드를 지켜보는 것이다.

응답 코드만 뽑아서 기다리기

새로고침을 반복하는 대신, 상태 코드만 찍는 폴링을 걸어 두었다.

1
2
3
4
5
URL=https://tuhbm.github.io/2026/11/12/nvidiaBoardJensenHuangDismissal/
until [ "$(curl -s -o /dev/null -w '%{http_code}' "$URL")" = "200" ]; do
  sleep 30
done
echo "live"
  • -s -o /dev/null은 본문을 버리고, -w '%{http_code}'는 상태 코드만 출력한다.
  • 200이 될 때까지 30초 간격으로 돈다. 너무 촘촘하게 칠 이유가 없다.
  • 끝나면 live가 찍히니, 다른 작업을 하다가 알림만 받으면 된다.

이 스크립트를 실제로 두 주소에 한 번씩 돌려 보니 열려 있는 글은 200, 없는 슬러그는 404가 나왔다. 그래서 “404 = 아직 안 열림 또는 주소 오타” 둘 중 하나로 읽으면 된다. 폴링을 걸기 전에 주소를 한 번 눈으로 확인하는 게 낫다. 오타 난 주소를 기다리면 영원히 안 끝난다.

이미지도 따로 확인한다

글 페이지가 열려도 대표 이미지가 안 열리는 경우가 있을까 싶어서, 첫 글을 확인할 때는 이미지 주소도 같이 쳐 본다.

1
2
curl -s -o /dev/null -w '%{http_code}\n' \
  https://tuhbm.github.io/images/normal/nvidiaBoardJensenHuangDismissal.png

둘 다 200이고, 메인 목록에도 글 슬러그가 보이면 그날 첫 글은 라이브로 판단한다. 목록 확인은 이렇게 한다.

1
curl -s https://tuhbm.github.io/ | grep -c nvidiaBoardJensenHuangDismissal

0이 아니면 목록에 노출된 것이다.

예약 글과 함께 쓰는 요령

이 블로그는 future: false라서 날짜가 미래인 글은 빌드에서 빠진다. 예약 빌드가 가끔 늦게 도는 날이 있어서, 그날 첫 글의 date를 지금보다 이른 시각(예: 08:45)으로 잡아 푸시한다. 푸시로 시작된 빌드에는 이미 시각이 지난 그 글이 들어가니 예약 빌드를 기다리지 않고 바로 열린다. 나머지 글은 날짜가 된 뒤 예약 빌드가 돌 때 한꺼번에 열린다.

여기서 주의할 점이 하나 있다. 예약 빌드가 한동안 안 돌면 나머지 글이 계속 안 열리는데, 이때는 빈 커밋을 푸시해 빌드를 한 번 더 일으키면 된다.

1
2
git commit --allow-empty -m "빌드 재실행"
git push

정리

  • master에 deploy: 커밋이 보이는 것과 사이트가 바뀐 것은 다른 일이다.
  • 404를 만나면 먼저 origin/master 최신 커밋의 해시가 내가 푸시한 해시인지 본다.
  • 해시가 맞으면 반영 지연이다. curl로 상태 코드를 폴링해 200이 될 때까지 기다린다.
  • 첫 글은 글 주소, 대표 이미지, 메인 목록 노출까지 세 곳을 확인한다.

아무리 자동화를 해도 마지막 한 단계의 지연은 내가 통제할 수 없다. 대신 “열렸는지”를 사람 눈 대신 코드가 확인하게 만들어 두면 기다리는 시간이 덜 불안하다.