깃허브 액션 CI/CD 초보 가이드 2026 — 자동 빌드·배포 첫걸음

이 페이지의 일부 링크는 제휴 링크이며, 구매 시 추가 비용 없이 소정의 수수료를 받을 수 있습니다.

짧은 결론

CI/CD는 "코드를 올리면 자동으로 검사하고, 검사를 통과하면 자동으로 내보내는" 반복 작업 자동화입니다.
GitHub Actions의 핵심 단위는 워크플로우 → 잡 → 스텝이고, 트리거(push, pull_request 등)가 이 흐름을 시작시킵니다.
가장 간단한 시작은 "push할 때마다 테스트 자동 실행"이고, 배포는 그 위에 조건을 얹어 확장하는 개념입니다.
초보가 자주 막히는 지점은 YAML 들여쓰기 오류와 시크릿(민감 정보) 관리 방식입니다.
처음부터 완벽한 파이프라인을 만들 필요는 없습니다. 테스트 자동화 → 빌드 자동화 → 배포 자동화 순으로 단계를 나눠 늘려가는 편이 실패가 적습니다.

CI/CD가 뭔가요

CI(Continuous Integration, 지속적 통합)는 코드를 자주 합치면서 그때마다 자동으로 테스트를 돌려 문제를 빨리 잡는 방식입니다. CD(Continuous Deployment/Delivery, 지속적 배포)는 그 검증을 통과한 코드를 자동으로 서버에 내보내는 단계까지 포함합니다. 둘을 합쳐 CI/CD라고 부르는데, 결국 핵심은 "사람이 매번 손으로 하던 반복 작업(테스트 실행, 빌드, 서버 업로드)을 코드가 대신하게 만든다"는 것입니다.

혼자 사이드 프로젝트를 할 때도 CI/CD는 의미가 있습니다. 코드를 고칠 때마다 "이거 배포 전에 뭐 빠뜨린 거 없나" 하고 손으로 확인하는 대신, 정해진 규칙대로 자동 검증이 돌아가면 실수를 줄일 수 있습니다.

GitHub Actions 기본 개념

GitHub Actions는 깃허브 저장소 안에서 바로 쓸 수 있는 CI/CD 도구입니다. 별도 서버나 외부 서비스 연동 없이 저장소에 설정 파일 하나만 추가하면 동작합니다. 구조는 아래처럼 계층적입니다.

용어	의미
워크플로우(Workflow)	`.github/workflows/` 안에 있는 YAML 파일 하나. 전체 자동화 단위
잡(Job)	워크플로우 안에서 실행되는 작업 묶음. 기본적으로 독립된 가상 머신에서 실행
스텝(Step)	잡 안의 개별 명령어 실행 단위. 순서대로 실행됨
트리거(Trigger)	워크플로우를 시작시키는 이벤트. `push`, `pull_request`, `schedule` 등
러너(Runner)	잡이 실제로 실행되는 가상 머신. 깃허브가 제공하는 러너를 기본으로 씀

정리하면 "트리거가 발생하면 → 워크플로우가 시작되고 → 그 안의 잡이 실행되며 → 잡은 여러 스텝을 순서대로 처리한다"는 흐름입니다.

아주 간단한 예시 — push할 때 테스트 실행

가장 흔한 첫걸음은 코드를 push할 때마다 테스트를 자동으로 돌리는 워크플로우입니다. 저장소 루트에 .github/workflows/test.yml 파일을 만들고 아래처럼 작성합니다.

name: Run Tests

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: 코드 가져오기
        uses: actions/checkout@v4

      - name: Node.js 설정
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 의존성 설치
        run: npm ci

      - name: 테스트 실행
        run: npm test

이 파일을 커밋하고 main 브랜치에 push하면, 깃허브가 자동으로 가상 머신을 하나 띄워 코드를 내려받고, Node.js를 설치하고, npm ci로 의존성을 깐 뒤 npm test를 실행합니다. 테스트가 실패하면 워크플로우도 실패로 표시되므로, "테스트 깨진 걸 모르고 넘어가는" 상황을 막을 수 있습니다.

배포까지 이어지는 큰 그림

테스트 자동화가 익숙해지면 다음 단계는 빌드와 배포입니다. 보통 아래 순서로 확장합니다.

1단계 — 테스트: push할 때마다 자동 테스트 (위 예시)
2단계 — 빌드: 테스트가 통과하면 npm run build처럼 실제 배포용 산출물을 만드는 스텝 추가
3단계 — 배포: 빌드 결과물을 서버나 호스팅 플랫폼에 업로드하는 스텝 추가

배포 대상은 정적 호스팅부터 컨테이너 기반 서버까지 다양한데, 서버를 직접 운영하는 구조라면 배포 스텝에서 SSH나 API로 접속해 새 빌드를 올리는 방식이 흔합니다. 이때 서버 자체의 설정 단순함과 요금 예측 가능성도 중요한데, DigitalOcean처럼 배포 절차가 단순한 플랫폼을 쓰면 GitHub Actions 워크플로우에서 배포 스텝을 짤 때 참고할 공식 문서와 예시가 많아 초보 단계에서 특히 수월합니다.

다만 배포 자동화는 실수하면 실제 서비스에 영향을 준다는 점에서 테스트 자동화보다 훨씬 신중해야 합니다. 처음에는 main 브랜치가 아니라 별도 스테이징 브랜치나 수동 승인(workflow_dispatch) 트리거로 연습해 보는 것을 권합니다.

초보가 자주 막히는 부분

YAML 들여쓰기 오류

GitHub Actions 설정 파일은 YAML 형식이고, YAML은 들여쓰기(스페이스 칸 수)로 구조를 구분합니다. 탭(tab)을 쓰면 오류가 나고, 스페이스 개수가 한 칸만 어긋나도 "이 항목이 어디 소속인지" 잘못 해석됩니다. 에디터에서 YAML 문법 검사 확장 기능을 켜두거나, 저장 전에 깃허브의 워크플로우 편집 화면에서 문법 오류 표시를 확인하는 습관이 필요합니다.

시크릿(민감 정보) 관리

배포 단계에서는 API 키, 서버 접속 정보 같은 민감한 값이 필요합니다. 이런 값을 YAML 파일에 그대로 적으면 저장소를 보는 모든 사람에게 노출됩니다. 깃허브 저장소의 Settings → Secrets and variables → Actions에서 값을 등록하면, 워크플로우 안에서는 ${{ secrets.MY_KEY }} 형태로만 참조하고 실제 값은 로그에도 노출되지 않습니다. 시크릿을 코드에 직접 적어두는 습관이 있다면 이 부분부터 먼저 고치는 것이 좋습니다.

잡 사이의 데이터 공유

잡은 기본적으로 독립된 가상 머신에서 실행되기 때문에, 한 잡에서 만든 빌드 결과물을 다른 잡에서 바로 쓸 수 없습니다. 이럴 때는 actions/upload-artifact와 actions/download-artifact로 결과물을 주고받아야 한다는 점을 놓치기 쉽습니다.

자주 묻는 질문

GitHub Actions는 무료인가요?

퍼블릭 저장소는 대부분 무료로 쓸 수 있고, 프라이빗 저장소는 매달 일정량의 무료 실행 시간을 제공한 뒤 초과분에 요금이 붙습니다. 정확한 한도는 요금제마다 다르므로 사용 전에 깃허브 공식 요금 정책을 확인하는 것이 안전합니다.

워크플로우가 실패하면 서비스에 바로 영향이 가나요?

아닙니다. 워크플로우 실패는 "자동화 절차 안에서 문제가 생겼다"는 뜻일 뿐, 배포 스텝까지 도달하지 않았다면 실제 서비스는 그대로입니다. 다만 배포 스텝 도중 실패하면 배포가 일부만 진행된 상태로 남을 수 있으니, 배포 자동화를 짤 때는 실패 시 되돌리는 절차(롤백)도 함께 고려하는 것이 좋습니다.

꼭 GitHub Actions를 써야 하나요?

아닙니다. Jenkins, GitLab CI, CircleCI 등 다른 CI/CD 도구도 많습니다. 다만 이미 GitHub에 코드를 올리고 있다면 별도 서비스 연동 없이 저장소 안에서 바로 설정할 수 있다는 점에서 진입 장벽이 낮은 편이라, 처음 CI/CD를 배우는 단계에서는 무난한 선택입니다.