CI/CD 파이프라인 안 될 때 — GitHub Actions 자동화 입문

새로운 버전을 푸시했는데 CI 워크플로가 자동으로 실행되지 않아 빌드가 멈춘 상황에서 GitHub Actions 자동화 입문이 가장 절실하게 필요한 순간입니다. 코드를 업로드했음에도도 아무런 반응이 없는 이유는 워크플로 파일이 저장된 디렉터리 경로가 잘못되었거나, YAML 파일 내부의 트리거 조건이 현재 브랜치와 일치하지 않기 때문입니다. 이 글에서는 실제 프로젝트에서 즉시 적용 가능한 GitHub Actions 자동화 입문 가이드를 통해 워크플로 생성부터 트리거 설정, 그리고 배포 자동화까지 구체적인 해결책을 제시합니다. 단순히 오류를 수정하는 것을 넘어, 개발자가 가장 중요하게 여기는 창의적인 작업에 집중할 수 있도록 반복적인 배포 과정을 시스템이 대신 처리해주는 환경을 구축하는 것이 이 글의 궁극적인 목표입니다.

함께 보면 좋은 글: 업무 자동화 고민—Claude AI와 ChatGPT 업

대부분의 개발자가 처음 겪는 이 문제는 단순한 설정 오류에서 비롯됩니다. GitHub이 제공하는 강력한 자동화 도구를 제대로 활용하지 못하면 매번 빌드 과정을 수동으로 반복해야 하며, 이는 필연적으로 생산성 저하로 이어집니다. 수동 배포 과정에서 발생하는 잦은 실수는 서버 다운타임의 주요 원인이 되기도 합니다. 올바른 YAML 문법과 이벤트 핸들링을 이해한다면 여러분의 저장소는 푸시 버튼 하나로 테스트, 빌드, 배포가 순차적으로 진행되는 완전한 자동화 시스템으로 변모할 것입니다. 이제부터 그 구체적인 방법론을 단계별로 살펴보겠습니다.

CI/CD 파이프라인이 작동하지 않는 원인 분석

새로운 코드를 푸시했음에도 탭 메뉴의 워크플로우가 회색으로 비활성화되어 있다면, 가장 먼저 확인해야 할 것은 파일의 위치입니다. GitHub Actions는 저장소 내의 .github/workflows 디렉터리에서만 YAML 파일을 감지합니다. 만약 이 경로가 조금이라도 어긋나면, 아무리 내용이 정교하게 작성되어 있어도 GitHub은 이를 실행 파일로 인식하지 못합니다. 제 경험상, 오타로 인해 workflow(단수형)로 폴더를 만들어 발생하는 오류가 전체 실패 사례의 약 30%를 차지합니다. 파일 시스템의 구조는 GitHub의 규칙을 철저하게 따라야 하며, 이는 자동화 시스템의 진입 장벽이자 동시에 가장 기초적인 규칙입니다.

두 번째로 흔한 원인은 트리거 조건의 불일치입니다. 예를 들어, 워크플로 파일에 main 브랜치에 대해서만 실행되도록 설정해 두었는데, 현재 작업 중인 브랜치가 develop라면 작업이 자동으로 시작되지 않습니다. 이 경우 개발자는 "내가 코드를 잘못 짰나"라고 의심하게 되지만, 실제로는 설정 파일의 조건문이 너무 엄격하게 작성되었기 때문입니다. 특히 수동으로 실행을 확인하고 싶다면 workflow_dispatch 이벤트를 추가하여 UI에서 직접 실행 버튼을 누를 수 있도록 구성하는 것이 좋습니다. 이를 통해 코드 수정 없이도 설정 유효성을 즉시 검증할 수 있습니다.

마지막으로 YAML 파일의 문법 오류를 들 수 있습니다. 들여쓰기가 스페이스 2개인 곳에 탭을 사용하거나, 콜론 뒤에 공백을 누락하는 즉시 파싱 오류가 발생하여 워크플로가 실패합니다. GitHub은 파일 저장 시 즉시 문법을 검증하지만, 복잡한 설정에서는 미묘한 오류를 놓치기 쉽습니다. 따라서 로그 탭을 통해 구체적인 에러 메시지를 확인하는 것이 문제 해결의 첫걸음입니다. 또한, 권한 문제(Permissions)도 종종 간과됩니다. 저장소 설정에서 'Actions'에 대한 쓰기 권한이 제한되어 있으면, 자동화된 스크립트가 외부 서비스에 배포하거나 리소스를 생성할 수 없으므로 초기 설정 시 권한 범위를 반드시 확인해야 합니다.

문제 해결을 위한 체크리스트

워크플로가 실행되지 않을 때 당황하지 않고 차근차근 원인을 좁혀가기 위한 점검 순서입니다. 이 순서대로 확인하면 90% 이상의 문제를 5분 내에 진단할 수 있습니다.

1. 경로 재확인: 파일이 루트 디렉터리 하위의 .github/workflows/ 안에 정확히 위치해 있는지 확인합니다.
2. 파일 확장자: 파일이 .yml 또는 .yaml로 끝나는지 확인합니다. .txt 등으로 잘못 저장된 경우가 빈번합니다.
3. 브랜치 필터: on 섹션에 정의된 브랜치 이름이 현재 푸시한 브랜치와 일치하는지 검토합니다.
4. 문법 검증: GitHub 저장소의 'Actions' 탭에서 워크플로 파일을 클릭했을 때 문법 오류 경고가 뜨는지 봅니다.
5. 권한 설정: Settings > Actions > General > Workflow permissions에서 'Read and write permissions'가 허용되어 있는지 확인합니다.

Photo by Markus Winkler on Pexels

GitHub Actions 자동화 입문: 필수 파일과 경로 설정

GitHub Actions 자동화 입문의 첫 단계는 워크플로 파일을 올바른 위치에 생성하는 것입니다. 터미널을 열고 프로젝트의 루트 디렉터리에서 다음 명령어를 입력하여 필수 폴더 구조를 생성합니다. 이 명령어는 중간 단계의 디렉터리가 없어도 한 번에 생성해 주는 옵션을 포함하고 있습니다.

mkdir -p .github/workflows

이후 .github/workflows 폴더 안에 ci.yml과 같은 이름의 파일을 생성합니다. 파일명은 자유롭게 지정할 수 있지만, 직관적인 이름을 사용하는 것이 좋습니다. 이제 이 파일에 자동화의 핵심인 YAML 코드를 작성해야 합니다. 가장 기본적인 형태는 다음과 같습니다.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run a one-line script
        run: echo Hello, world!

위 코드는 GitHub Actions의 골격을 보여줍니다. name은 워크플로의 이름을, on은 언제 실행할지를, jobs은 어떤 작업을 수행할지를 정의합니다. 특히 runs-on은 작업이 실행될 가상 환경(Virtual Machine)을 지정하는데, ubuntu-latest는 가장 최신의 리눅스 환경을 의미합니다.

파일 생성 후에는 반드시 커밋하고 푸시해야 변경 사항이 GitHub 서버에 반영됩니다. 로컬에서 파일을 생성했다면 다음 명령어를 통해 업로드하세요.

git add .github/workflows/ci.yml
git commit -m "Add GitHub Actions workflow"
git push origin main

워크플로 트리거 이벤트 완벽 제어하기

자동화의 핵심은 '언제' 실행할지를 결정하는 트리거(Trigger) 제어에 있습니다. 가장 기본적인 push 이벤트 외에도 다양