본문 바로가기

CI/CD 기초 개념 소개

GitHub Actions로 푸시와 풀 리퀘스트마다 빌드를 검사하는 워크플로를 만들고, 지속적 통합·제공·배포의 차이를 구분합니다.

앞 글에서 만든 구조는 편리하지만 위험한 면이 있습니다. main 브랜치에 푸시하면 곧바로 배포가 시작되므로, 실수가 섞인 코드도 같은 길로 나갑니다. 혼자 만드는 연습 앱에서는 괜찮지만, 여럿이 하루에도 몇 번씩 코드를 합치는 프로젝트에서는 합치기 전에 누군가 매번 확인해 주어야 합니다. 그 확인을 사람 대신 기계가 하게 만드는 것이 이 글의 주제입니다.

이 글을 읽고 나면 다음을 할 수 있습니다.

  • GitHub Actions 워크플로를 만들어, 푸시와 풀 리퀘스트마다 앱이 빌드되는지 자동으로 검사합니다.
  • 검사가 실패했을 때 로그에서 원인을 찾아 고칩니다.
  • 지속적 통합, 지속적 제공, 지속적 배포를 구별합니다.

정적 호스팅 배포에서 GitHub 저장소와 Netlify에 연결한 deploy-practice 프로젝트를 이어서 씁니다. 브랜치를 만들고 풀 리퀘스트(pull request)를 여는 과정이 나오므로, 낯설다면 Git 기초와 협업 워크플로우를 함께 봅니다.


1단계: 푸시할 때마다 빌드해 보는 워크플로 만들기

GitHub Actions는 저장소에 어떤 일이 생겼을 때 GitHub의 서버에서 정해 둔 명령을 실행해 주는 기능입니다. 무엇을 언제 실행할지는 저장소의 .github/workflows 폴더에 YAML 파일로 적으며, 이 파일 하나를 워크플로(workflow)라고 부릅니다. 프로젝트 루트에 폴더를 만들고 다음 파일을 저장합니다. YAML은 들여쓰기로 구조를 나타내므로 공백의 개수를 그대로 맞춥니다.

.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: npm
      - run: npm ci
      - run: npm run build

on은 언제 실행할지를 정합니다. 여기서는 main에 푸시됐을 때와 풀 리퀘스트가 열리거나 갱신됐을 때입니다. jobs 아래의 build는 실행할 작업 하나의 이름이고, runs-on은 그 작업을 돌릴 가상 컴퓨터의 종류입니다. steps는 그 컴퓨터에서 위에서 아래로 실행할 단계입니다.

네 단계가 하는 일은 새 컴퓨터에서 프로젝트를 처음 받아 빌드할 때와 같습니다. actions/checkout이 저장소의 코드를 내려받고, actions/setup-node가 Node.js를 설치합니다. npm ci는 package-lock.json에 적힌 버전 그대로 의존성을 설치하고, npm run build가 앱을 빌드합니다. 어느 단계든 실패하면 뒤 단계는 실행되지 않고 작업 전체가 실패로 끝납니다. 예제의 @v7은 checkout과 setup-node의 공식 릴리스에서 확인한 메이저 버전입니다. 이후 버전도 각 액션의 릴리스에서 확인합니다.

파일을 커밋하고 푸시합니다.

git add .
git commit -m "빌드 검사 워크플로 추가"
git push

GitHub 저장소 화면에서 Actions 탭을 엽니다. 방금 푸시한 커밋의 이름으로 실행 기록이 하나 생겨 있고, 잠시 뒤 초록색 체크 표시로 바뀌면 성공입니다. 기록을 누르고 build 작업을 누르면 단계마다의 출력을 펼쳐 볼 수 있습니다. npm run build 단계의 출력은 내 컴퓨터에서 빌드할 때 터미널에 나오던 것과 같은 내용입니다.

이것이 지속적 통합(Continuous Integration, CI)의 가장 작은 형태입니다. 코드가 저장소에 들어올 때마다 정해 둔 검사를 자동으로 돌려, 문제가 생긴 시점을 바로 알 수 있게 합니다.


2단계: 빌드가 깨진 코드를 풀 리퀘스트로 올려 보기

검사가 실제로 무엇을 막아 주는지 보려면 실패하는 코드를 올려 보아야 합니다. main을 직접 건드리지 않도록 새 브랜치에서 작업합니다.

git switch -c footer

App.jsx에 푸터를 달려고 합니다. 맨 위에 임포트를 더하고, Routes가 끝난 바로 아래에 Footer를 놓습니다. 그런데 Footer.jsx 파일을 만드는 것을 잊었다고 합시다.

src/App.jsx (더한 두 곳)
import Footer from './Footer';

// </Routes> 바로 아래
<Footer />

이 상태로 커밋하고 브랜치를 푸시합니다.

git add .
git commit -m "푸터 추가"
git push -u origin footer

GitHub 저장소 화면에 나타나는 Compare & pull request 버튼을 눌러 footer에서 main으로 가는 풀 리퀘스트를 만듭니다. 이때 배포된 사이트는 어떻게 될까요? 그리고 풀 리퀘스트 화면에는 무엇이 보일까요? 먼저 예상해 보세요.

결과 확인하기

배포된 사이트는 그대로입니다. Netlify가 사이트로 내보내는 것은 main 브랜치인데, main에는 아직 아무것도 들어가지 않았습니다.

풀 리퀘스트 화면의 아래쪽에는 CI의 build 검사가 빨간 X로 표시됩니다. 워크플로의 on에 pull_request가 있으므로, 풀 리퀘스트가 열리자 GitHub가 이 브랜치의 코드로 네 단계를 실행했고 npm run build 단계가 실패했습니다. 검사 옆의 링크로 로그를 열면 ./Footer를 찾지 못했다는 빌드 오류가 보입니다. Netlify도 풀 리퀘스트마다 미리보기 배포를 만들려고 하므로, Netlify의 검사가 함께 실패로 보일 수 있습니다.

합치기 전에 문제가 드러났습니다. 이제 빠뜨린 파일을 만듭니다.

src/Footer.jsx
export default function Footer() {
  return <footer>deploy-practice</footer>;
}

같은 브랜치에 커밋하고 푸시합니다.

git add .
git commit -m "Footer 컴포넌트 파일 추가"
git push

풀 리퀘스트 화면에서 검사가 다시 실행되고, 이번에는 초록색 체크로 바뀝니다. 이제 Merge pull request를 눌러 합칩니다. 합치는 순간 main에 새 커밋이 들어가므로 두 가지 일이 일어납니다. Actions 탭에는 main의 푸시로 실행된 기록이 하나 더 생기고, Netlify의 Deploys 화면에는 새 배포가 시작됩니다. 배포가 끝난 사이트의 맨 아래에 "deploy-practice"라는 푸터가 보이면 한 바퀴를 다 돈 것입니다.

마지막으로 내 컴퓨터의 main을 저장소와 맞춥니다.

git switch main
git pull

방금 한 일에 이름 붙이기: CI와 두 가지 CD

지금까지 만든 흐름에는 서로 다른 일 세 가지가 들어 있습니다.

지속적 통합(CI)은 변경을 자주 합치고, 합칠 때마다 빌드와 테스트를 자동으로 돌려 문제를 일찍 찾는 방법입니다. 1단계의 워크플로가 이 일을 합니다. 지금은 빌드만 검사하지만, 테스트를 작성한 프로젝트라면 npm test 단계를 더해 기존 기능이 깨지지 않았는지도 확인합니다.

CD는 두 가지 말의 줄임입니다. 지속적 제공(Continuous Delivery)은 검사를 통과한 결과를 언제든 내보낼 수 있는 상태로 자동으로 준비해 두고, 실제로 내보내는 결정은 사람이 내리는 방식입니다. 지속적 배포(Continuous Deployment)는 그 마지막 결정까지 자동으로 해서, 검사를 통과하면 사람의 승인 없이 운영 환경에 나갑니다. main에 들어온 커밋을 곧바로 사이트로 내보내는 Netlify의 기본 동작은 지속적 배포입니다. 새 배포를 만들기만 하고 사이트에 게시하는 일은 사람이 버튼으로 하도록 Netlify의 자동 게시를 꺼 두면 지속적 제공이 됩니다.

commit과 lockfile → 정적 검사·테스트 → production build → preview 확인 → 수동 승인 또는 자동 정책 → 운영과 모니터링. 앞 검증 실패는 뒤 배포를 막도록 구성하며, 같은 아티팩트 승격·롤백은 직접 설계하는 절차입니다.

CI / CONTINUOUS DELIVERY / DEPLOYMENT

검증 후, 수동 승인과 자동 배포를 구분합니다

CI는 변경을 자주 통합하고 빌드·테스트로 피드백합니다. 검증을 통과한 릴리스를 준비한 뒤 수동 승인으로 운영에 내보내면 지속적 제공, 자동으로 내보내면 지속적 배포입니다.

검증 후, 수동 승인과 자동 배포를 구분합니다commit과 lockfile → 정적 검사·테스트 → production build → preview 확인 → 수동 승인 또는 자동 정책 → 운영과 모니터링. 앞 검증 실패는 뒤 배포를 막도록 구성하며, 같은 아티팩트 승격·롤백은 직접 설계하는 절차입니다.
1. 입력 기록commit · lockfile
연결 관계1. 입력 기록 · commit · lockfile → 2. 검사 · 테스트 · 실패 시 뒤 단계 중지
2. 검사 · 테스트실패 시 뒤 단계 중지
연결 관계2. 검사 · 테스트 · 실패 시 뒤 단계 중지 → 3. production build · dist 아티팩트 생성
3. production builddist 아티팩트 생성
연결 관계3. production build · dist 아티팩트 생성 → 4. preview 검증 · 대표 URL · 기능
4. preview 검증대표 URL · 기능
연결 관계4. preview 검증 · 대표 URL · 기능 → 5. 릴리스 방식 선택 · 수동 승인 / 자동 정책
5. 릴리스 방식 선택수동 승인 / 자동 정책
연결 관계5. 릴리스 방식 선택 · 수동 승인 / 자동 정책 → 6. 운영 + 모니터링 · 오류 · 핵심 행동 확인
6. 운영 + 모니터링오류 · 핵심 행동 확인

단계와 의존성을 구성해야 실패가 배포를 차단합니다

검증과 릴리스 의존 조건의 모바일 흐름입력→검사→빌드→preview→수동 승인 또는 자동 정책→운영 모니터링 순서입니다. 필요한 선행 검증이 실패하면 후속 배포를 차단하도록 별도로 구성합니다. 이 그림은 실패 분기와 자동 rollback을 다루지 않습니다.1. 입력 기록commit · lockfile2. 검사 · 테스트실패 시 뒤 단계 중지3. production builddist 아티팩트 생성4. preview 검증대표 URL · 기능5. 릴리스 방식 선택수동 승인 / 자동 정책6. 운영 + 모니터링오류 · 핵심 행동 확인

CI / FEEDBACK

검증 실패는 수정으로 되돌립니다

commit·lockfile로 입력을 기록하고 정적 검사·테스트·빌드의 기준과 순서를 구성합니다. 실패 소유자와 재실행 방법을 기록하며, 필요한 앞 단계가 실패하면 뒤 배포가 진행되지 않도록 의존성을 둡니다.

ARTIFACT / VERIFY

검증한 결과물을 보존합니다

정적 앱의 dist 파일을 아티팩트로 저장합니다. 선택한 preview·스테이징에서 대표 URL, 자산, 오류 상태와 접근성을 확인합니다. 같은 아티팩트의 승격은 이 그림의 설계 예시입니다.

CONTINUOUS DELIVERY

준비는 자동화, 운영 배포는 승인

검증된 릴리스를 운영에 내보낼 수 있는 상태로 준비합니다. 최종 배포는 사람이 승인하거나 수동으로 시작합니다.

CONTINUOUS DEPLOYMENT

기준을 통과하면 운영에 자동 반영

구성한 검사와 정책을 통과하면 별도 수동 승인 없이 운영으로 배포합니다. 저장소 연결 자체가 테스트 기준이나 배포 차단 조건을 모두 만들어 주는 것은 아닙니다.

OBSERVE / ROLLBACK

운영 결과와 복구 대상을 기록합니다

release ID·digest와 오류·핵심 사용자 행동을 기록합니다. 이전 정상 아티팩트로 돌아갈 정책을 구성하고 확인합니다. digest 기록·원자적 전환·자동 롤백은 각 도구에서 직접 구성할 절차입니다.

이 흐름은 파이프라인 설계 예시입니다. Netlify·Vercel의 Git 연동이나 GitHub Actions 사용만으로 검사 의존성, 승인, 동일 바이트 승격과 모니터링·롤백이 모두 갖춰지지는 않습니다.

위 그림은 이 과정을 여섯 단계로 펼친 것입니다. 앞의 세 단계인 커밋, 검사와 테스트, 프로덕션 빌드가 CI에 해당합니다. 넷째 단계에서 빌드 결과를 미리보기 환경에서 확인하고, 다섯째 단계에서 수동 승인과 자동 정책으로 갈라지는 곳이 지속적 제공과 지속적 배포의 차이입니다. 그림의 아티팩트(artifact)는 파이프라인이 보관했다가 다음 단계로 넘기는 빌드 결과, 곧 dist 폴더를 가리킵니다. 여섯째 단계인 운영과 관찰은 배포한 뒤에 오류와 사용자의 행동을 지켜보는 일로, 이 글에서는 다루지 않습니다.


검사가 실패하면 배포도 멈추게 하려면

지금의 구성에는 빈틈이 하나 있습니다. GitHub Actions의 검사와 Netlify의 배포는 서로를 모릅니다. 2단계에서 문제를 막은 것은 검사 결과를 보고 병합을 미룬 사람이었습니다. 빨간 X를 무시하고 Merge pull request를 누르거나 main에 직접 푸시하면, Netlify는 검사 결과와 상관없이 빌드를 시도합니다. 이번처럼 빌드 자체가 깨진 코드는 Netlify의 빌드도 실패해서 게시되지 않지만, 빌드는 되는데 테스트가 실패하는 코드라면 그대로 나갑니다.

검사를 통과해야만 다음 단계로 가게 하는 방법은 두 가지가 있습니다. 하나는 GitHub 저장소의 브랜치 보호 규칙에서 main에 병합하기 전에 통과해야 할 검사를 지정하는 것입니다. 다른 하나는 배포까지 워크플로 안에 넣고, 배포 작업이 검사 작업에 의존하게 만드는 것입니다. 워크플로에서는 작업에 needs를 적어 앞 작업이 성공해야 실행되게 합니다(GitHub Actions의 jobs.needs 문법). 실제 프로젝트의 파이프라인은 대개 다음 표처럼 단계마다 통과 조건을 정해 둡니다.

단계통과 조건실패하면
검사린트와 테스트가 모두 성공빌드하지 않음
빌드npm run build 성공, dist 생성배포할 것이 없음
미리보기 확인미리보기 주소에서 주요 화면과 깊은 주소가 열림병합이나 승인을 하지 않음
배포앞 단계가 모두 통과(지속적 제공이라면 사람의 승인까지)사이트는 이전 배포 그대로

테스트를 포함해 여러 작업으로 이루어진 워크플로를 실제로 구성하는 예는 CI/CD 파이프라인 구축에서 볼 수 있습니다.


기대와 다를 때 먼저 볼 곳

증상먼저 확인할 곳
Actions 탭에 기록이 생기지 않음파일이 .github/workflows/ 안에 있는지, 확장자가 .yml인지, 푸시한 브랜치가 on의 조건에 맞는지
워크플로 파일의 푸시만 거부됨GitHub에 로그인할 때 쓴 토큰에 워크플로를 고칠 권한이 있는지
실행하자마자 문법 오류로 실패YAML의 들여쓰기. 탭이 아니라 공백인지
npm ci 단계에서 실패package-lock.json이 저장소에 올라가 있는지, package.json과 맞는지
내 컴퓨터에서는 되는데 npm run build 단계가 실패새로 만든 파일을 커밋에 넣었는지. 임포트 경로의 대소문자가 실제 파일 이름과 같은지

마지막 줄의 대소문자는 자주 겪는 문제입니다. Windows와 macOS의 기본 파일 시스템은 ./footer와 ./Footer를 같은 파일로 찾아 주지만, 워크플로가 도는 Linux에서는 다른 파일입니다.


더 깊이: npm ci와 같은 커밋의 다른 결과물

워크플로에서 npm install 대신 npm ci를 쓴 데에는 이유가 있습니다. npm 문서의 npm ci에 따르면 이 명령은 테스트와 지속적 통합, 배포 같은 자동화 환경을 위한 것입니다. package-lock.json이 반드시 있어야 하고, lockfile의 내용이 package.json과 맞지 않으면 lockfile을 고치는 대신 오류로 멈춥니다. 이미 있는 node_modules는 지우고 새로 설치하며, package.json과 lockfile에는 아무것도 쓰지 않습니다. 같은 상황에서 npm install은 lockfile을 고쳐 가며 설치를 이어 가므로, 내 컴퓨터에서 확인한 것과 다른 버전으로 빌드될 수 있습니다. 의존성을 바꾸는 일은 내 컴퓨터에서 npm install로 하고, 바뀐 lockfile을 함께 커밋합니다.

같은 커밋이라고 빌드 결과가 같은 파일이라는 뜻은 아닙니다. 이 글의 구성에서는 GitHub Actions가 한 번, Netlify가 한 번, 같은 커밋을 따로 빌드합니다. 검사한 dist와 배포된 dist는 서로 다른 컴퓨터에서 만들어졌고, 환경 값이나 Node.js 버전이 다르면 내용도 달라질 수 있습니다. 이 차이를 없애려는 파이프라인은 한 번 빌드한 결과물을 보관해 두고, 검증을 마친 바로 그 파일을 운영 환경으로 옮깁니다. 앞의 그림이 빌드 결과를 아티팩트로 저장한다고 적은 것이 이 설계입니다.


정리

  • 지속적 통합은 코드가 들어올 때마다 빌드와 테스트를 자동으로 돌려 문제를 일찍 찾는 방법입니다.
  • GitHub Actions의 워크플로는 .github/workflows의 YAML 파일이며, on에 실행 조건을, steps에 실행할 단계를 적습니다.
  • 풀 리퀘스트에서 검사를 돌리면 main에 합치기 전에 문제를 볼 수 있고, 그동안 배포된 사이트는 바뀌지 않습니다.
  • 지속적 제공은 내보낼 준비까지 자동으로 하고 마지막 결정을 사람이 내립니다. 지속적 배포는 그 결정까지 자동으로 합니다.
  • 검사와 배포가 따로 돌면 검사 실패가 배포를 막지 못합니다. 브랜치 보호 규칙이나 작업 사이의 의존 관계로 둘을 이어야 합니다.

연습 문제

1. 테스트는 실패했는데 사이트가 바뀌었다면

어떤 저장소의 워크플로는 npm test를 실행하고, 호스팅 서비스는 main에 푸시될 때마다 따로 빌드해 배포합니다. 누군가 main에 직접 푸시했더니 워크플로의 테스트는 실패했고 호스팅 서비스의 빌드는 성공해 사이트가 바뀌었습니다. 이 저장소는 "테스트를 통과한 코드만 배포한다"고 말할 수 있을까요?

해설 보기

말할 수 없습니다. 테스트와 배포가 같은 푸시에 따로 반응했을 뿐, 테스트의 결과가 배포의 조건으로 이어져 있지 않습니다. 테스트가 실패했다는 사실은 Actions 탭에 남지만 사이트는 이미 바뀌었습니다.

테스트 통과를 배포의 조건으로 만들려면 main에 직접 푸시하지 못하게 하고 풀 리퀘스트의 검사를 필수로 지정하거나, 배포 작업이 needs로 테스트 작업에 의존하도록 워크플로 안에서 배포합니다.

2. 승인 버튼이 있는 배포

검사와 빌드가 통과하면 결과물이 자동으로 미리보기 주소에 올라가고, 담당자가 화면을 확인한 뒤 승인 버튼을 눌러야 운영 사이트에 나갑니다. 이것은 지속적 제공과 지속적 배포 가운데 어느 쪽일까요?

해설 보기

지속적 제공입니다. 내보낼 준비는 자동으로 끝나지만 운영에 내보내는 결정은 사람이 내립니다. 승인 버튼을 누른 뒤의 배포 작업 자체가 자동이라는 점은 구분에 영향을 주지 않습니다. 승인 단계를 없애 검사를 통과하면 곧바로 나가게 하면 지속적 배포가 됩니다.

3. npm ci가 package.json을 찾지 못하는 워크플로 고치기

다음 워크플로는 npm ci 단계에서 package.json을 찾지 못해 실패합니다. 저장소의 루트에는 package.json과 package-lock.json이 분명히 있습니다. 원인을 찾아 고쳐 보세요.

.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
      - run: npm ci
      - run: npm run build
해설 보기

작업은 아무 파일도 없는 새 가상 컴퓨터에서 시작합니다. 저장소의 코드를 내려받는 단계가 없으므로 npm ci를 실행한 폴더는 비어 있습니다. steps의 맨 앞에 actions/checkout을 더합니다.

.github/workflows/ci.yml (steps)
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
      - run: npm ci
      - run: npm run build

단계는 위에서 아래로 실행되므로 순서도 중요합니다. 코드를 받은 뒤에 의존성을 설치하고, 그 뒤에 빌드합니다.

4. 빌드 앞에 린트 검사 넣기

Vite의 React 템플릿은 코드의 흔한 실수를 찾아 주는 린터와 npm run lint 스크립트를 함께 만들어 줍니다. deploy-practice의 package.json에 lint 스크립트가 있는지 확인하고, 워크플로가 빌드 전에 린트를 실행하게 만들어 보세요.

  • 풀 리퀘스트를 열면 설치, 린트, 빌드의 순서로 실행됩니다.
  • 린트가 오류를 보고하면 빌드 단계는 실행되지 않고 검사가 실패합니다.
  • 작업은 새 브랜치에서 하고, 풀 리퀘스트의 검사가 초록색이 된 뒤에 병합합니다.
해설 보기

먼저 내 컴퓨터에서 npm run lint를 실행해 지금 코드가 통과하는지 봅니다. 오류가 나오면 메시지가 가리키는 줄을 먼저 고칩니다. 그다음 새 브랜치에서 워크플로에 한 줄을 더합니다.

git switch -c add-lint
.github/workflows/ci.yml (steps)
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run build

커밋하고 git push -u origin add-lint로 올린 뒤 풀 리퀘스트를 엽니다. 실행 기록의 build 작업을 열어 npm run lint 단계가 npm run build 단계보다 앞에 있고 둘 다 성공했는지 확인합니다. 단계는 차례로 실행되고 하나가 실패하면 뒤 단계를 건너뛰므로, 린트가 실패하면 빌드는 실행되지 않습니다. 검사가 초록색이면 병합하고, 내 컴퓨터에서 git switch main과 git pull로 맞춥니다.

다음 글 React 생태계와 추가 학습 자원 소개에서는 이 교재 다음에 무엇을 배울지를, 지금 만드는 앱에서 생긴 문제를 기준으로 고르는 방법을 살펴봅니다.