CI 구축했는데 빌드 안 될 때 — GitHub Actions 자동화 입문

새 프로젝트에 CI 파이프라인을 처음 구축하며 GitHub Actions 자동화 입문을 시도하는데, 코드를 푸시할 때마다 빌드가 멈춰버려 진행이 안 되는 상황입니다. 문제의 원인을 파악하지 못해 푸시할 때마다 실패 알림만 쌓이고, 로그를 봐도 어디서부터 손을 대야 할지 막막할 때가 많습니다. 이 문제는 대부분 워크플로우 파일의 미세한 문법 오류, 의존성 설치 시간 초과, 혹은 러너 환경의 리소스 부족 때문에 발생합니다. 배포 파이프라인은 현대적 소프트웨어 개발의 심장과도 같아서, 이곳이 멈추면 개발 속도 전체가 저하되곤 합니다. 특히 초보자에게는 '검은 상자'와 같은 CI 서버의 내부 작동 방식을 이해하는 것이 큰 산입니다. 이 글에서는 로그 확인부터 의존성 캐싱, 로컬 디버깅 도구 활용까지 GitHub Actions 자동화 입문 과정에서 겪는 빌드 실패를 해결하는 구체적인 방법을 설명합니다.

함께 보면 좋은 글: 팀 회의록 자동 요약, 노션 AI 기능 활용법 실무 딱

GitHub Actions 자동화 입문, 실패 원인 분석하기

빌드가 멈추는 현상을 해결하려면 가장 먼저 실행 로그를 통해 어디서 병목이 발생하는지 확인해야 합니다. GitHub Actions 웹 인터페이스의 'Actions' 탭에서 실패한 워크플로우 실행을 클릭한 후, 왼쪽의 단계 목록을 살펴보면 빨간색 X 표시가 있는 단계를 쉽게 찾을 수 있습니다. 실제 사용자는 이 상황에 대해 "배경지식이 없다보니 쉽지 않네요"라고 토로한 바 있으며, 이는 설정의 복잡성보다 디버깅 방법을 몰라 겪는 어려움을 시사합니다(출처: clien.net).

로그를 확인할 때는 npm install나 bundle install과 같은 의존성 설치 단계에서 시간이 지나도록 멈춰 있는 경우가 가장 흔합니다. 이는 네트워크 지연이나 패키지 서버의 과부하, 혹은 설치해야 할 패키지의 양이 너무 많아 발생합니다. 또한 스크립트 자체의 무한 루프나 서버 연결 대기 시간 초과도 원인이 될 수 있습니다. 로그 하단에 'Error: Process completed with exit code'와 같은 메시지가 있다면 명령어 자체의 실패를 의미하며, 아무런 메시지 없이 그냥 멈춰 있다면 타임아웃 설정이 필요한 상황입니다.

GitHub Actions의 러너(Runner)는 매번 새로운 가상 머신 환경을 제공합니다. 따라서 로컬 환경에서는 발생하지 않던 '깨끗한 상태'에서의 설치 문제가 드러나기도 합니다. 특히 메모리 집약적인 작업을 수행할 때 러너의 리소스 한계(2코어 CPU, 7GB RAM)를 초과하면 프로세스가 강제 종료(Killed)되며 로그가 남지 않는 경우도 많습니다. 이때는 로그의 'Set up job' 단계에서 할당된 리소스를 확인하고, 워크플로우를 분리하여 병렬 실행하거나 무거운 작업을 별도의 서버에서 처리하는 방식으로 전환해야 합니다.

로그 분석 5단계 체크리스트

Photo by Mumtaz Niazi on Pexels

워크플로우 파일 문법 및 타임아웃 설정

GitHub Actions 자동화 입문 단계에서 가장 많이 하는 실수는 YAML 파일의 들여쓰기 오류입니다. 워크플로우 파일인 .github/workflows/main.yml은 스페이스 2칸 기준의 엄격한 들여쓰기를 요구하며, 탭이나 잘못된 공백은 즉시 문법 오류를 유발합니다. GitHub 문서에 따르면 워크플로우 파일은 리포지토리의 루트 디렉토리 내 지정된 경로에 있어야만 자동으로 감지됩니다(출처: GitHub Actions 공식 문서).

빌드가 멈추는 현상을 방지하는 가장 확실한 설정은 각 작업별로 timeout-minutes을 지정하는 것입니다. 이 값을 설정하지 않으면 기본적으로 6시간 동안 멈춰 있는 작업을 기다리게 됩니다. 예를 들어, 테스트나 빌드는 10분 내에 끝나도록 설정하여 문제가 발생했을 때 빠르게 실패 처리하고 알림을 받을 수 있습니다. 또한, 특정 스텝에만 타임아웃을 설정하여 민감한 작업을 더 세밀하게 제어할 수도 있습니다. 다음은 타임아웃이 포함된 기본 워크플로우 예시입니다.

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10 # Job 전체 타임아웃
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run build
      run: npm run build
      
    - name: Run tests
      run: npm test
      timeout-minutes: 5 # 테스트 단계에만 짧은 타임아웃 적용

위 예시의 runs-on: ubuntu-latest는 GitHub에서 제공하는 최신 우분투 러너를 사용한다는 의미이며, actions/checkout@v4는 코드를 러너로 가져오는 필수 액션입니다. timeout-minutes: 10 설정은 이 작업이 10분 이상 지속되면 강제로 중단시켜 자원 낭비를 막습니다. 실제로 한 사용자는 "Private repositories with unlimited collaborators are now available for all GitHub accounts"와 같은 변경 사항을 언급하며 리소스 관리의 중요성을 강조한 바 있습니다(출처: clien.net).

복잡한 워크플로우를 작성할 때는 YAML의 env 섹션을 적극 활용하여 환경 변수를 관리하는 것이 좋습니다. 이는 설정의 가독성을 높이고, API 키나 DB 접속 정보 같은 민감한 정보는 secrets 컨텍스트를 통해 안전하게 주입받아야 합니다. 만약 워크플로우가 수행되지 않는다면, 브랜치 보호 규칙(Branch Protection Rules)이나 트리거 조건(on) 설정이 의도한 대로 되어 있는지 재검토해야 합니다.

의존성 캐싱으로 빌드 시간 단축하기

빌드가 멈추는 듯한 현상은 실제로는 매번 동일한 패키지를 처음부터 다시 설치하는 과정에서 발생하는 지연일 가능성이 높습니다. GitHub Actions 자동화 입문에서 성능 최적화의 핵심은 의존성 캐싱입니다. 캐싱을 사용하면 패키지 매니저가 node_modules나 vendor 디렉토리를 다시 다운로드하는 대신, 이전에 저장해 둔 아카이브를 불러와 설치 시간을 획기적으로 줄입니다. 특히 프론트엔드 프로젝트에서 node_modules는 수만 개의 파일을 포함하므로 이를 매번 다운로드하는 것은 엄청난 비용이 듭니다.

actions/cache 액션을 사용하여 캐싱을 구현할 수 있습니다. 캐시 키(Key)는 보통 패키지 잠금 파일인 package-lock.json의 해시값을 사용하여, 의존성이 변경되었을 때만 새로운 캐시를 생성하도록 설정합니다. GitHub 캐시 저장소는 리포지토리당 10GB의 용량 제한이 있으며, 7일 동안 액세스가 없는 캐시는 자동으로 삭제됩니다(LRU 정책). 따라서 불필요한 파일을 캐싱 키에 포함시키지 않도록 주의해야 합니다. 다음은 Node.js 프로젝트에서 의존성을 캐싱하는 설정 예시입니다.

- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

이 설정은 러너의 운영체제(runner.os)와 package-lock.json의 해시를 조합하여 고유한 캐시 키를 생성합니다. restore-keys는 정확한 키를 찾지 못했을 때 접두사가 일치하는 가장 최근 캐시를 복원하는 데 사용됩니다. 실제로 Next.js 프로젝트에서 이 캐싱을 적용했을 때, 3분 이상 걸리던 설치 과정이 30초대로 단춐된 사례가 있습니다. Python 프로젝트에서도 path: ~/.cache/pip를 지정하고 requirements.txt를 해싱하여 동일한 효과를 낼 수 있습니다.