Post

[기록] GitHub 빌드 실패 해결하기

7월 1일부터 갑자기 GitHub 블로그 빌드가 실패하기 시작했다.
기존에 잘 사용하던 템플릿으로 텍스트만 바꿔서 포스트를 작성했을 뿐인데, 어느 순간부터 배포가 되지 않았다.

Image

이번 글에서는 해당 문제의 원인을 추적하고 해결한 과정을 기록해 본다.


🚨 빌드 에러 발생


포스팅 내용은 단순히 제목만 바꿨을 뿐인데, 갑작스럽게 빌드 에러가 발생했다.

빌드 로그를 확인해보니까 아래와 같은 에러 메시지가 확인되었다.

1
* At _site/posts/boj-30684-java/index.html:116:

Image

해당 파일을 확인해보았다.

에디터를 사용해서 파일 자체를 확인해보니까 라인이 맞지 않았다.

Image

로컬에서 개발자 모드로 확인한 결과, 다음과 같은 빈 링크가 존재하고 있었다.

1
<a href=""></a>

Image

검색해보니 Jekyll에서 빈 링크가 있을 경우 빌드가 실패할 수 있다는 것을 확인했다.
관련 이슈 참고


1️⃣ 해결하자 1: 테스트 브랜치 생성 및 테스트


로컬에서 페이지만 확인했을 땐 잘 보이지만 원격 repo에 올리면 빌드가 실패했기 때문에, hotfix/build-error라는 새로운 브랜치를 생성해서 테스트를 진행했다.

지금 빌드되는 브랜치가 main으로 잡혀있기 때문에 블로그에 접속해서 확인해보려면 설정을 바꿔야 한다.

repo - Settings - Pages - Build and deployment에서 브랜치를 새로 만든 브랜치로 바꿔주고 테스트를 시작했다.

Image

테스트 시작.

에러가 발생한 .md 파일을 확인해보니 링크 라인과 주석 라인이 한 줄로 인식되게 적혀있었다.

Image

마크다운 문법상 줄바꿈을 하려면 줄 끝에 공백 두 칸을 추가하거나 명시적으로 빈 줄을 넣어야 한다. 그렇지 않으면 연속된 라인으로 처리된다.

Image

로컬 서버를 열어서 확인해보면 <a href>가 제거된 것을 볼 수 있다.

Image

그래서 원격 repo에 push해서 빌드가 잘 되는지 확인해본다.

업로드 후 에러 없이 정상적으로 빌드되었음을 확인했다.

Image

하지만 블로그 접속 시 반영이 되지 않아 브랜치 설정 문제를 의심하게 되었다.


2️⃣ 해결하자 2: 브랜치 설정 문제


브랜치 설정 문제를 확인하기 위해서 테스트 페이지를 현재 depoly branch로 설정되어 있는 hotfix/build-error에 테스트 페이지를 업로드 했다.

Image

이것 역시 빌드는 잘 되는데 블로그에 적용이 안 된다.



(+ 25.07.08 추가)

Github Actions를 알아보다가 알게된 건데 테마를 받을 때 Github Actions 설정도 가져왔었다.

.yml 파일을 보니까 deploy branches 설정이 되어있더라.

1
2
3
4
5
6
7
8
9
10
name: "Build and Deploy"
on:
  push:
    branches:
      - main
      - master
    paths-ignore:
      - .gitignore
      - README.md
      - LICENSE

그래서 repo setting을 바꿔도 빌드가 그 브랜치로 되지 않았었다.

만약 setting을 바꿔서 브랜치를 바꾸려면 branches:- '*'로 바꿔야 한다.



main 브랜치에도 같은 테스트 페이지를 업로드 해본다.

Image

테스트 페이지에는 링크를 거는 내용이 없음에도 또 <a> 태그가 문제라는 에러가 뜬다.

그럼 각각 포스팅의 문제가 아니라는 뜻이다.

(물론 위에서 말한 링크 라인과 주석 라인이 한 줄로 인식되게 적혀있었는 건 수정을 하긴 해야한다.)


3️⃣ 해결하자 3: 블로그 테마 설정 되돌리기 (롤백)

빌드 실패가 처음 발생한 시점 전에 변경한 내용을 살펴보니까 카테고리 세분화를 하기 위해서 카테고리 구조를 바꿨었다.

Image

그리고 9cb305c 커밋으로 올린 글 말고 전부 404가 뜨고 있었다.

이걸로 유추하기론 높은 확률로 이 부분이 문제인 것 같다. (수정을 하면서도 찝찝하긴 했다.)

카테고리 설정 바꾼 것이 꼭 필요한 수정이 아니었던지라 그냥 설정 파일 변경 전으로 커밋 롤백을 진행하기로 했다.

롤백 전에 백업용 브랜치 생성했다.

Image

그 다음 문제 발생 전 커밋(bb8536e 커밋)으로 강제 롤백을 진행했다.

Image

롤백 진행 시 강제 푸시를 진행하기 때문에 협업 시에는 함부로 진행하면 안 되지만 혼자 쓰는 블로그용 repo기 때문에 그냥 사용했다.

(협업 시 사용하면 공동 작업자의 커밋을 날려버릴 수 있음)

1
2
3
git reset --hard [커밋 해시]

git push origin main --force

Image

롤백 끝.

Image

4️⃣ 해결하자 4: 롤백한 커밋 재배포 하기

롤백은 그냥 커밋만 되돌린 것이기 때문에 자동으로 배포가 되지 않는다.

그래서 빈 커밋을 하나 만들어줬다.

1
2
3
git commit --allow-empty -m "trigger redeploy"

git push origin main

Image

근데 빌드 진행이 안 됐다.

Image

아마 파일이 수정되어야 자동 배포가 진행되는 것 같다.

그래서 그냥 의미 없는 수정을 하고 커밋을 했다.

Image

정상적으로 배포가 됐고 404뜨던 게시글들도 다 잘 보였다.

Image

역시 구조는 함부로 건드는 것이 아니다…

5️⃣ 해결하자 5: 백업 브랜치에서 필요한 커밋 가져오기 (cherry-pick)

롤백을 하면서 사라진 포스트들이 있기 때문에 backup 브랜치에서 cherry-pick으로 필요한 커밋들을 가져온다.

1
2
3
git cherry-pick [커밋 해시]

git push origin main

Image

적용 완료.

Image

빌드도 잘 되었고, 블로그도 정상적으로 동작한다!

Image

👍 오늘도 해결! 👍

✨ 핵심 포인트


  • 로컬에서는 잘 보여도 빌드 과정에서 문제가 생길 수 있다.

  • Jekyll 테마에 따라 빈 <a> 태그는 빌드 오류를 유발할 수 있다.

  • 문제 해결을 할 땐 브랜치를 나눠서 테스트하자.

  • ⭐ 구조는 함부로 건드는 것이 아니다.

  • 지금 블로그 설정으로는 파일이 변경되어야 자동으로 배포된다.

  • --allow-empty로 파일 수정 없이 빈 커밋을 생성할 수 있다.

  • cherry-pick으로 원하는 커밋만 가져올 수 있다.


© juyeoon. All rights reserved.