[Github Actions] anthropics/claude-code-action@v1 갑자기 실패하는 이슈 (Claude Code native binary not found)

🚨 갑자기 실패하기 시작한 워크플로우

평소처럼 잘 돌아가던 GitHub Actions 워크플로우가 어느 순간부터 빨간불이 뜨기 시작했다. 

로그를 확인해보니 아래와 같은 에러 메시지가 찍혀 있었다.

Action failed with error: SDK execution error: ReferenceError: 
Claude Code native binary not found at /home/runner/.local/bin/claude. 
Please ensure Claude Code is installed via native installer or 
specify a valid path with options.pathToClaudeCodeExecutable.

Claude Code 바이너리를 /home/runner/.local/bin/claude 경로에서 찾을 수 없다는 내용이다.

🔎 원인 파악

확인해보니 floating tag(@v1)가 가리키는 최신 릴리즈가 바뀌면서 발생한 문제였다.

• 최신: v1.0.113 (오늘 01:41 UTC 릴리즈) → 실패 https://github.com/anthropics/claude-code-action/releases/tag/v1.0.113
• 직전: v1.0.112 → 성공 https://github.com/anthropics/claude-code-action/releases/tag/v1.0.112

GitHub 이슈에도 동일한 증상이 올라와 있다. https://github.com/anthropics/claude-code-action/issues/1290

이슈에 정리된 근본 원인을 요약하면 다음과 같다.

 

1) claude install이 바이너리를 설치하지 못했는데도 exit 0으로 종료됨

설치 스크립트가 아래와 같은 경고를 띄우면서도, 종료 코드 0(성공)으로 빠져나온다.

Setting up launcher and shell integration...
⚠ Setup notes:
  ● installMethod is native, but directory /home/runner/.local/bin does not exist
  ● installMethod is native, but claude command not found at /home/runner/.local/bin/claude

✔ Claude Code successfully installed!
  Version: 2.1.129
  Location: ~/.local/bin/claude

successfully installed 라고 떠 있지만, 사실 바이너리가 해당 경로에 존재하지 않는 상태다.

 

2) claude-code-action 측에서 바이너리 존재 여부를 검증하지 않음

installClaudeCode() 내부에서 exit code만 믿고 ${HOME}/.local/bin/claude 경로를 그대로 반환한 뒤, 이후 단계에서 그 경로로 posix_spawn을 호출하면서 ENOENT 에러가 터지는 구조다.

즉, 워크플로우 코드의 문제가 아니라 액션 쪽 릴리즈 이슈다.

🛠️ 임시 해결 방법

이슈가 해결될 때까지 사용할 수 있는 우회 방법은 두 가지가 있다.

1. 직전 버전으로 핀 고정 (가장 확실함)

@v1 같은 floating tag 대신, 정상 동작하던 직전 버전으로 명시적으로 고정한다.

# 변경 전
- uses: anthropics/claude-code-action@v1

# 변경 후
- uses: anthropics/claude-code-action@v1.0.112

더 안전하게 가려면 commit SHA로 핀하는 방법도 있다. (GitHub에서는 일반적으로 third-party action을 SHA로 고정하는 것을 권장한다.)

 

- uses: anthropics/claude-code-action@<v1.0.112의 commit SHA>

2. plugin_marketplaces 옵션 제거

이슈 본문에 따르면, plugin_marketplaces 설정을 사용 중일 때 문제가 발생한다. 해당 기능을 굳이 쓰지 않는다면 옵션을 빼는 것만으로도 워크플로우는 다시 통과한다.

 

# 영향 받는 설정 예시
- uses: anthropics/claude-code-action@v1
  with:
    plugin_marketplaces: https://github.com/anthropics/claude-code.git
    plugins: code-review@claude-code-plugins

plugin_marketplaces와 plugins를 제거하면 marketplace/plugin 설치 단계가 통째로 스킵되어 에러를 우회할 수 있다.

💡 마무리하며

이번 이슈를 겪으면서 새삼 느낀 점은, @v1 같은 floating tag는 편하지만 이런 식으로 갑자기 깨질 수 있다는 것이다.

• floating tag (@v1, @latest) → 자동으로 최신을 따라가서 편하지만, 깨질 위험 있음
• 명시적 버전 (@v1.0.112) → 안정적이지만, 보안 패치/기능 업데이트는 수동으로 따라가야 함
• commit SHA 고정 → 가장 안전하지만, 가독성과 유지보수 비용이 가장 큼

CI/CD 안정성이 중요한 메인 워크플로우라면, production 레벨에서는 SHA 또는 패치 버전까지 명시하는 방향이 안전하다는 걸 이번 기회에 다시 확인할 수 있었다.

 

이슈가 해결되면 다시 @v1로 되돌리거나 새 패치 버전으로 업데이트할 예정이다.

같은 에러를 겪고 계신 분들께 도움이 되었으면 한다. 🙏