GitHub Actions deprecated 에러 해결 — Gatsby 빌드 실패 대처법

안녕하세요, 자바파커입니다.

잘 돌아가던 블로그 빌드가 갑자기 실패했습니다. 코드는 하나도 안 건드렸는데요.

GitHub Actions에서 deprecated 버전 에러가 발생하면서 빌드가 멈추는 경험을 하셨다면, 이 포스팅이 도움이 될 겁니다. 저도 같은 상황을 겪고 해결한 과정을 공유합니다.

문제 상황: 갑자기 빌드가 안 된다

GitHub Actions 빌드 로그에 이런 에러가 나타났습니다.

Error: This request has been automatically failed because it uses a deprecated
version of `actions/upload-artifact: v3`.

코드를 전혀 수정하지 않았는데, GitHub 측에서 Actions v3 지원을 중단하면서 기존 워크플로우가 동작하지 않게 된 것입니다.

원인: GitHub Actions v3 지원 종료

GitHub는 2024년부터 단계적으로 Actions v3를 deprecated 처리했고, 결국 v3 기반 워크플로우는 자동으로 실패하게 되었습니다. 영향을 받는 주요 액션은 다음과 같습니다.

해결 1: Actions 버전 업데이트

.github/workflows/gatsby.yml 파일에서 모든 액션 버전을 최신으로 변경합니다.

# Before (deprecated)
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- uses: actions/configure-pages@v3
- uses: actions/cache@v3
- uses: actions/upload-pages-artifact@v2
- uses: actions/deploy-pages@v2

# After (최신)
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- uses: actions/configure-pages@v5
- uses: actions/cache@v4
- uses: actions/upload-pages-artifact@v3
- uses: actions/deploy-pages@v4

이것만으로 deprecated 에러는 해결됩니다. 하지만 저는 여기서 끝나지 않았습니다.

해결 2: remark-math 호환성 에러

Actions 버전을 올리고 다시 빌드했더니, 이번에는 다른 에러가 나타났습니다.

TypeError: Cannot set properties of undefined (setting 'math')
  - block.js:203 Function.blockPlugin
    [javapark.github.io]/[remark-math]/block.js:203:24

원인을 추적해보니, gatsby-remark-katex@3.10.0이 의존하는 remark-math@1.0.6이 gatsby-transformer-remark@6의 unified@9와 호환되지 않는 것이었습니다.

KaTeX 수식 기능을 사용하지 않고 있었기 때문에, 과감히 제거하기로 했습니다.

제거 순서

1. gatsby-config.js에서 플러그인 제거

// 아래 블록 삭제
{
  resolve: `gatsby-remark-katex`,
  options: {
    strict: `ignore`,
  },
},

2. package.json에서 패키지 제거

// 아래 두 줄 삭제
"gatsby-remark-katex": "^3.5.0",
"katex": "^0.12.0",

3. gatsby-browser.js에서 CSS import 제거

// 아래 줄 삭제
require("katex/dist/katex.min.css")

이 세 번째 단계를 놓치면 빌드 시 Can't resolve 'katex/dist/katex.min.css' 에러가 발생합니다. 패키지를 제거할 때는 설정 파일, 의존성, import 경로를 모두 확인해야 합니다.

정리: 체크리스트

Gatsby 블로그에서 GitHub Actions 빌드가 실패했다면 아래 순서로 확인하세요.

1. 워크플로우 파일의 Actions 버전이 deprecated되지 않았는지 확인
2. 버전 업데이트 후에도 빌드가 실패하면, 플러그인 호환성 문제를 의심
3. 사용하지 않는 플러그인은 설정 + 패키지 + import 3곳 모두 정리
4. gatsby clean으로 캐시를 지우고 다시 빌드

FAQ

GitHub Actions v3는 언제부터 deprecated인가요?

2024년 4월에 deprecation이 공지되었고, 이후 단계적으로 강제 실패 처리되었습니다. 자세한 내용은 GitHub 공식 변경 로그에서 확인할 수 있습니다.

사용 중인 플러그인이 호환되지 않으면 어떻게 하나요?

해당 플러그인이 필수라면 호환되는 버전 조합을 찾아야 합니다. 선택적이라면 제거하는 것이 가장 깔끔합니다. gatsby-transformer-remark의 메이저 버전을 내리는 것은 다른 플러그인에 영향을 줄 수 있어 추천하지 않습니다.

gatsby clean은 언제 실행해야 하나요?

플러그인을 추가/제거했거나, 빌드 에러가 이해되지 않을 때 npx gatsby clean을 실행하면 캐시 관련 문제를 해결할 수 있습니다.

다음 포스팅에서는 Gatsby 블로그의 검색 기능을 대폭 개선한 경험을 공유합니다. 태그 검색, AND/OR 검색, 관련도 정렬까지 외부 서비스 없이 구현하는 방법을 다룹니다.

여러분도 Actions 빌드 에러를 겪으셨나요? 어떻게 해결하셨는지 댓글로 공유해주세요!