GitHub Actions로 CI/CD 파이프라인 구축하기 실전 가이드

GitHub Actions를 활용해 CI/CD 파이프라인과 배포 자동화를 구축하는 방법을 워크플로우 작성부터 시크릿 관리, 최적화까지 실무 관점에서 단계별로 정리했습니다.

코드를 푸시할 때마다 테스트가 자동으로 돌고, 검증을 통과한 커밋만 배포되는 환경은 이제 선택이 아니라 기본입니다. GitHub Actions는 별도의 CI 서버를 구축하지 않고도 저장소 안에서 CI/CD 파이프라인을 구성할 수 있어 진입 장벽이 낮습니다. 이 글에서는 워크플로우 파일 작성부터 배포 자동화, 실무에서 자주 놓치는 최적화 포인트까지 순서대로 다룹니다.

GitHub Actions 워크플로우의 기본 구조

GitHub Actions는 저장소의 .github/workflows 디렉터리에 YAML 파일을 두면 동작합니다. 하나의 워크플로우는 이벤트(on), 잡(jobs), 그리고 잡 안의 스텝(steps)으로 구성됩니다. 각 잡은 독립된 러너에서 실행되며, 기본적으로 병렬로 돌아가지만 needs 키워드로 실행 순서를 제어할 수 있습니다.

• on 필드로 push, pull_request, schedule 등 트리거 조건을 지정합니다.
• jobs는 각각 별도의 가상 환경에서 실행되어 서로 격리됩니다.
• steps는 순차적으로 실행되며 uses로 액션을, run으로 셸 명령을 지정합니다.
• runs-on으로 ubuntu-latest 같은 러너 환경을 선택합니다.
• needs를 사용하면 이전 잡이 성공해야 다음 잡이 실행됩니다.

처음에는 테스트 실행 잡 하나만 만들어 동작을 확인하고, 이후 빌드와 배포 잡을 점진적으로 추가하는 방식을 권장합니다. 한 번에 복잡한 파이프라인을 작성하면 어느 단계에서 실패했는지 파악하기 어렵습니다.

CI 단계: 테스트와 빌드 자동화

CI의 핵심은 병합 전에 코드 품질을 자동으로 검증하는 것입니다. pull_request 이벤트를 트리거로 삼아 린트, 유닛 테스트, 빌드를 순차적으로 실행하면 문제가 있는 코드가 메인 브랜치로 들어오는 것을 막을 수 있습니다. 의존성 설치는 매번 반복되므로 캐시를 적극 활용해야 실행 시간을 줄일 수 있습니다.

• actions/checkout으로 저장소 코드를 러너에 가져옵니다.
• 언어별 setup 액션(setup-node, setup-python 등)으로 런타임을 구성합니다.
• actions/cache 또는 setup 액션의 cache 옵션으로 의존성을 캐싱합니다.
• matrix 전략으로 여러 버전이나 OS에서 동시에 테스트합니다.
• 테스트 실패 시 잡이 중단되어 병합을 차단하도록 브랜치 보호 규칙과 연동합니다.

CI 파이프라인은 빠를수록 지켜집니다. 실행에 10분이 넘게 걸리면 개발자는 결과를 기다리지 않고 다음 작업으로 넘어가며, 결국 파이프라인이 방치됩니다.

CD 단계: 안전한 배포 자동화

CD는 검증을 통과한 코드를 실제 환경에 배포하는 단계입니다. 여기서 가장 중요한 것은 배포 조건을 명확히 하고 민감 정보를 안전하게 다루는 것입니다. main 브랜치 푸시나 태그 생성처럼 특정 이벤트에만 배포가 트리거되도록 제한하고, 인증 키는 반드시 GitHub Secrets에 저장해 코드에 노출되지 않게 해야 합니다.

• Secrets에 API 토큰과 배포 자격 증명을 저장하고 로그에 출력되지 않게 합니다.
• environment 기능으로 스테이징과 프로덕션을 구분하고 승인 절차를 둡니다.
• if 조건문으로 특정 브랜치나 태그에서만 배포 잡이 실행되게 합니다.
• 배포 실패에 대비해 롤백 스텝이나 헬스체크를 포함합니다.
• OIDC를 활용하면 장기 자격 증명 없이 클라우드에 인증할 수 있습니다.

프로덕션 배포에는 environment의 수동 승인(required reviewers)을 걸어두면, 자동화 속에서도 최종 확인이라는 안전장치를 유지할 수 있습니다.

실행 시간과 비용 최적화

파이프라인이 자리를 잡으면 실행 시간과 비용이 다음 과제가 됩니다. 불필요한 잡 실행을 줄이고 캐시를 재활용하는 것만으로도 상당한 개선이 가능합니다. 특히 모노레포에서는 변경된 부분만 검증하도록 경로 필터를 거는 것이 효과적입니다.

• paths 필터로 관련 파일이 변경됐을 때만 워크플로우를 실행합니다.
• concurrency 설정으로 같은 브랜치의 이전 실행을 자동 취소합니다.
• 자주 사용하는 셋업 과정을 composite action으로 묶어 재사용합니다.
• timeout-minutes로 멈춘 잡이 러너를 오래 점유하지 않게 합니다.
• 무거운 통합 테스트는 nightly 스케줄로 분리해 PR 파이프라인을 가볍게 유지합니다.

DevCowork로 파이프라인 가시성 확보하기

파이프라인을 구축한 뒤에는 팀 전체가 배포 상태를 함께 파악하는 것이 중요합니다. DevCowork는 GitHub Actions의 워크플로우 실행 결과를 팀 대시보드에 연동해, 어떤 커밋이 어느 환경까지 배포됐는지 한눈에 보여줍니다. 배포 실패나 승인 대기 상태를 팀 채널로 알려주기 때문에 로그를 일일이 확인하지 않아도 되고, 릴리스 이력이 이슈·PR과 함께 정리되어 협업 맥락을 잃지 않고 배포 흐름을 추적할 수 있습니다.