DevOps on kenji.blog

【Git 명령】rebase와 merge의 차이와 실무에서의 올바른 사용법

Sun, 13 Sep 2026 09:00:00 +0900

1. 들어가며：왜 “merge인가 rebase인가"는 영원한 숙제인가

Git은 현대 소프트웨어 개발에 있어서 필수적인 버전 관리 시스템입니다. 여러 개발자가 동시에 코드베이스를 변경할 때, Git의 강력한 브랜치 모델이 위력을 발휘합니다. 하지만, 팀 개발에서 “merge와 rebase 중 어느 것을 사용해야 하는가"라는 논쟁은 초보자부터 숙련자까지 항상 개발자를 괴롭히는 주제 중 하나입니다.

이 글에서는 Git의 내부 구조인 DAG(방향 비순환 그래프)와 커밋 해시의 수학적 성질을 통해, git merge와 git rebase의 메커니즘 차이를 깊이 파헤칩니다. 그리고 실무에서 이것들을 어떻게 구분해서 사용해야 하는지, 구체적인 워크플로우와 함께 철저하게 해설합니다. 단순한 명령어 소개에 그치지 않고, 이면에서 Git이 어떤 계산을 하고 있는지까지 이해함으로써, 충돌(Conflict)에 대한 두려움을 없애고 깔끔하고 추적 가능한 이력을 구축할 수 있게 됩니다.

2. Git의 내부 구조：커밋 해시와 객체 모델

Git이 이력을 어떻게 통합하는지 이해하기 위해서는 먼저 Git이 데이터를 어떻게 저장하고 있는지 알아야 합니다. Git은 단순한 파일 변경의 차이(패치)를 저장하는 것이 아니라, 특정 시점의 파일 시스템 전체의 스냅샷을 저장하고 있습니다.

2.1 커밋 해시의 암호학적 성질

Git의 각 커밋은 그 내용을 바탕으로 계산된 SHA-1(Secure Hash Algorithm 1) 해시 함수에 의한 40자리 16진수로 고유하게 식별됩니다. 커밋 객체는 다음 요소들로 구성됩니다:

Tree 객체에 대한 포인터: 그 시점의 디렉토리 구조와 파일(Blob)의 스냅샷
부모 커밋에 대한 포인터: 1개 이상의 부모 커밋의 해시값 (첫 커밋은 부모를 가지지 않으며, 병합 커밋은 2개 이상의 부모를 가집니다)
작성자 정보(Author): 코드를 작성한 사람과 일시
커미터 정보(Committer): 커밋을 생성하고 적용한 사람과 일시
커밋 메시지: 변경의 의도를 설명하는 텍스트

수학적으로 표현하면, 커밋 객체 $C$ 에 대한 해시값 $H(C)$ 는 다음과 같이 정의됩니다：

$$ H(C) = \text{SHA-1}( \text{tree} \parallel \text{parent} \parallel \text{author} \parallel \text{committer} \parallel \text{message} ) $$

여기서 $\parallel$ 은 데이터의 결합을 나타냅니다. 해시 함수의 특성에 따라, 커밋 메시지를 1글자만 바꾸거나 부모 커밋이 다르기만 해도 전혀 다른 해시값이 생성됩니다. 즉, 커밋은 불변(Immutable) 입니다. 후술할 rebase가 “이력을 조작한다"고 표현되는 것은 실제로는 “내용은 비슷하지만 다른 해시값을 가지는 새로운 커밋을 생성하고 있기” 때문입니다.

해시 공간의 크기는 $2^{160}$ 이며, 충돌(다른 커밋이 같은 해시값을 가지는 것)이 발생할 확률 $P$ 는 생일 문제(Birthday Paradox)의 이론을 사용하면 다음과 같이 근사할 수 있습니다 ($n$ 은 커밋 수)：

$$ P(\text{collision}) \approx 1 - \exp\left(-\frac{n^2}{2 \times 2^{160}}\right) $$

이 확률은 극히 낮아 실용상 Git의 커밋 해시가 충돌하는 일은 거의 있을 수 없습니다.

3. 그래프 이론과 DAG：Git 이력의 수학적 모델

Git의 커밋 이력은 그래프 이론의 “방향 비순환 그래프(Directed Acyclic Graph, DAG)“로 모델링됩니다.

3.1 DAG(방향 비순환 그래프)란

그래프 $G = (V, E)$ 에서, $V$ 는 커밋의 집합(정점), $E$ 는 커밋 간의 부모-자식 관계를 나타내는 방향 간선(Directed Edge)의 집합입니다. Git에서는 간선의 방향이 “자식 커밋에서 부모 커밋"으로 향합니다. 새로운 커밋은 과거의 커밋에 대한 포인터를 가지고 있기 때문입니다.

graph BT
A["Commit A (초기)"]
B["Commit B"]
C["Commit C (Main)"]
D["Commit D (Feature)"]
E["Commit E (Merge)"]
B --> A
C --> B
D --> B
E --> C
E --> D

DAG의 가장 큰 특징은 “사이클(순환)이 존재하지 않는다"는 것입니다. 이로 인해 커밋 이력을 거슬러 올라가는 알고리즘은 무한 루프에 빠지지 않고 확실하게 종단(초기 커밋)에 도달할 수 있습니다.

3.2 위상 정렬(Topological Sort)과 이력의 순서

Git의 git log 명령어 등으로 이력을 표시할 때, DAG는 위상 정렬(Topological Sort) 알고리즘에 의해 1차원의 리스트로 순서가 매겨집니다. DAG에서의 임의의 방향 간선 $u \to v$ ($u$ 는 $v$ 의 자식)에 대해, 리스트 내에서 $u$ 가 $v$ 보다 앞에 오도록 정렬합니다.

4. git merge의 메커니즘과 종류

브랜치의 변경을 통합하는 가장 기본적인 명령어가 git merge입니다. 하지만 현재 상태에 따라 Git은 다른 병합 전략을 자동으로 선택합니다.

4.1 Fast-Forward 병합 (–ff)

통합 대상(예: main)의 브랜치가 통합할(예: feature) 브랜치의 직접적인 조상일 경우, Git은 “Fast-Forward(빨리 감기)” 병합을 실행합니다. 이는 새로운 커밋을 생성하지 않고 단순히 브랜치의 포인터를 앞으로 이동시키는 작업입니다.

gitGraph
commit id: "A"
commit id: "B"
branch feature
checkout feature
commit id: "C"
commit id: "D"
checkout main
merge feature

Fast-Forward 병합은 이력을 일직선으로 유지하지만, “어떤 커밋들이 하나의 기능 개발(feature)로 묶여 있었는지"에 대한 컨텍스트가 손실되는 단점이 있습니다.

4.2 Non-Fast-Forward 병합 (–no-ff)

git merge --no-ff를 명시적으로 지정하면, Fast-Forward가 가능한 상황이더라도 반드시 새로운 “병합 커밋"을 생성합니다. 병합 커밋은 2개의 부모를 가지는 특별한 커밋입니다.

gitGraph
commit id: "A"
commit id: "B"
branch feature
checkout feature
commit id: "C"
commit id: "D"
checkout main
commit id: "Main 작업 1"
merge feature type: NORMAL

이 방법의 이점은 기능 브랜치의 존재와 역사가 DAG 상에 명확하게 남는다는 것입니다. 문제가 발생했을 때 git revert -m 1 <병합 커밋의 해시>를 실행하여 기능 전체를 한 번에 안전하게 취소(리버트)할 수 있습니다.

4.3 3방향 병합(3-Way Merge) 알고리즘

통합 대상과 통합할 브랜치가 각각 독자적인 커밋을 가지고 있는 경우, Git은 3방향 병합을 실행합니다. 이 때 Git은 DAG를 탐색하여 두 브랜치의 “공통 조상(Lowest Common Ancestor, LCA)“을 찾아냅니다.

LCA를 찾기 위한 알고리즘의 시간 복잡도 $T_{\text{LCA}}$ 는 정점 수 $|V|$ 와 간선 수 $|E|$ 에 대해 선형 시간에 실행 가능합니다：

$$ T_{\text{LCA}} = \mathcal{O}(|V| + |E|) $$

Git은 “LCA의 상태”, “현재 브랜치의 상태”, “상대 브랜치의 상태” 3가지를 비교하여 변경 사항이 충돌하지 않으면 자동으로 병합 커밋을 생성합니다.

5. git rebase의 메커니즘과 이력의 재구성

git merge가 이력을 “통합"하는 반면, git rebase는 이력을 “재구성(다시 붙이기)“합니다.

5.1 Rebase의 이면에 있는 동작

feature 브랜치를 main 브랜치로 리베이스(git rebase main)할 때의 내부 동작은 다음과 같습니다：

feature 브랜치와 main 브랜치의 공통 조상(LCA)을 찾는다.
LCA부터 feature 브랜치 끝까지의 커밋 차이를 임시 영역에 저장한다.
feature 브랜치의 포인터를 main 브랜치의 끝으로 이동시킨다.
저장해둔 차이를 새로운 베이스(main의 끝) 위에 하나씩 순차적으로 적용(Cherry-Pick)하여 새로운 커밋을 생성한다.

graph TD
A["Commit A"] --> B["Commit B"]
B --> C["Commit C (Main)"]
B --> D["Commit D (이전 Feature)"]
D -.-> E["Commit D' (새로운 Feature)"]
C --> E
style D stroke-dasharray: 5 5, fill: #f9f9f9, color: #999

여기서 중요한 것은 리베이스로 인해 생성된 커밋 $D'$ 는 원래의 커밋 $D$ 와 부모 커밋이 다르기 때문에 완전히 다른 해시값을 가진다는 것입니다 (앞서 설명한 해시 함수의 정의 $H(C)$ 참조).

5.2 인터랙티브 리베이스(Interactive Rebase)

git rebase -i (또는 --interactive)를 사용하면 커밋 이력을 마음대로 조작할 수 있습니다. 이는 로컬 이력을 정리하기 위한 가장 강력한 도구입니다.

pick : 커밋을 그대로 적용한다.
reword : 커밋 메시지만 수정한다.
edit : 커밋 내용을 수정하기 위해 일시 정지한다.
squash : 이 커밋을 이전 커밋에 합치고, 메시지도 결합한다.
fixup : squash와 같지만, 이 커밋의 메시지는 파기한다.
drop : 커밋을 완전히 삭제한다.

수학적으로 보면, 어떤 브랜치에 $N$ 개의 커밋이 있을 경우 리베이스의 순서 변경으로 생성 가능한 선형 이력의 변형(순열) $P$ 는 다음과 같습니다.

$$ P = N! $$

Git은 개발자에게 $N!$ 가지의 자유를 주어 이력을 논리적이고 아름다운 상태로 유지할 수 있게 해줍니다.

6. 리베이스의 황금률(The Golden Rule of Rebase)

rebase는 매우 강력하지만 하나의 절대적인 규칙이 존재합니다.

“공개된 퍼블릭한 이력에 대해서는 절대 리베이스를 해서는 안 된다” (Never rebase public history)

6.1 왜 퍼블릭 이력을 리베이스하면 안 되는가?

Git은 분산형입니다. 당신이 origin/main에 푸시한 커밋은 다른 개발자의 로컬 저장소에도 클론(복제)되어 있습니다. 만약 당신이 이미 푸시한 커밋을 리베이스하여 이력을 조작하고 git push --force로 강제 덮어쓰기를 한다면 무슨 일이 일어날까요?

다른 개발자의 로컬에 있는 DAG와 리모트의 DAG가 근본적으로 분기되어 버립니다. 다른 개발자가 git pull을 실행하면 Git은 다른 역사를 가진 커밋 뭉치를 억지로 병합하려고 시도하고, 대량의 충돌이나 중복 커밋(동일한 변경 내용이지만 해시가 다른 커밋)이 발생하여 저장소가 패닉 상태에 빠집니다.

리베이스는 **“아직 아무와도 공유하지 않은 로컬 브랜치”**에 대해서만 수행하는 것이 철칙입니다.

7. 충돌(Conflict) 해결과 git rebase –continue

여러 사람이 같은 파일의 같은 부분을 변경한 경우 충돌이 발생합니다. merge와 rebase에서는 충돌을 해결하는 과정이 다릅니다.

7.1 Merge에서의 충돌 해결

git merge의 경우 충돌 해결은 한 번만 발생합니다. 최종적인 병합 커밋을 생성하기 직전에 모든 충돌 지점을 한 번에 수정합니다.

7.2 Rebase에서의 충돌 해결

git rebase의 경우 커밋을 하나씩 다시 적용해 나가는 특성상 각 커밋마다 충돌이 발생할 가능성이 있습니다.

리베이스 중에 충돌이 발생하면 Git은 처리를 일시 정지합니다. 해결 흐름은 다음과 같습니다：

에디터나 IDE(VS Code 등)를 열어 충돌 마커(<<<<<<< 나 ======, >>>>>>>)를 수동으로 수정한다.
수정한 파일을 인덱스에 추가한다：
1

git add <수정한 파일>
커밋은 생성하지 않고 리베이스 처리를 재개한다：
1

git rebase --continue

만약 리베이스 자체를 취소하고 원래 상태로 되돌리고 싶다면 다음 명령어를 실행합니다：

1

git rebase --abort

(※ 충돌 해결이 필요 없고 해당 커밋을 통째로 건너뛰고 싶을 때는 git rebase --skip을 사용합니다)

8. 실무에서의 올바른 사용법(워크플로우 실천)

그렇다면 실제 개발 현장에서는 merge와 rebase를 어떻게 구분해서 사용해야 할까요? 여기서는 가장 표준적이고 안전한 접근 방식을 소개합니다.

8.1 【시나리오 1】 로컬 작업 이력 정리(Rebase 활용)

기능 브랜치에서 개발 중, 자잘한 커밋(“오타 수정”, “임시 저장” 등)이 많이 쌓였다고 가정해 봅시다. 풀 리퀘스트(PR)를 올리기 전에, 이것들을 의미 있는 단위로 정리하기 위해 인터랙티브 리베이스를 사용합니다.

1
2
3


# feature 브랜치에 있는 상태에서 실행
git rebase -i HEAD~5
# (에디터가 열리면 squash나 fixup을 사용하여 이력을 정리한다)

이를 통해 리뷰어에게 의도가 잘 전달되는 아름다운 커밋 이력을 만들 수 있습니다.

8.2 【시나리오 2】 최신 main 브랜치 따라가기(Rebase 활용)

개발이 길어지고 main 브랜치에 다른 사람들의 변경 사항이 계속 병합되는 경우, 자신의 feature 브랜치가 구버전이 되어 버립니다. 이 경우 feature 브랜치를 최신 main으로 리베이스하여 변경 사항을 쫓아갑니다.

1
2
3
4
5


# main의 최신 정보를 가져옴
git fetch origin

# feature 브랜치를 최신 main 위에 다시 이어 붙임
git rebase origin/main

이로 인해 이력이 일직선이 되어 나중에 병합할 때의 충돌을 방지할 수 있습니다. 또한, 불필요한 병합 커밋(“Merge branch ‘main’ into feature”)이 생성되는 것을 막을 수 있습니다.

8.3 【시나리오 3】 완성된 기능 통합(Merge 활용)

feature 브랜치에서의 개발이 완료되고 마침내 main 브랜치에 통합하는 단계입니다. 여기서는 **git merge --no-ff**를 사용합니다 (GitHub 등의 Pull Request에서 “Create a merge commit"을 선택하는 것과 동일합니다).

1
2
3


git checkout main
git merge --no-ff feature -m "Merge feature: 사용자 로그인 기능 구현"
git push origin main

이로 인해 main 브랜치의 DAG 상에 “여기서 하나의 기능이 병합되었다"는 역사의 결절점(병합 커밋)이 남습니다. 나중에 이력을 볼 때 기능 단위로 코드를 추적하기 쉬워집니다.

9. 결론(요약)

Git을 조작할 때 “모든 것을 Merge로 해결한다"거나 “모든 것을 Rebase로 일직선으로 만든다"와 같은 극단적인 접근 방식은 각각 장단점이 있습니다.

실무에서의 모범 사례는 **“로컬의 프라이빗한 이력은 rebase로 아름답게 정리하고, 퍼블릭한 통합 이력은 merge –no-ff로 문맥을 남긴다”**는 하이브리드 접근 방식입니다.

로컬(개인의 작업 공간): rebase를 사용하여 불필요한 커밋을 배제하고, 최신 메인 라인을 따라가며 일직선의 이력을 유지한다.
글로벌(공유 작업 공간): merge --no-ff를 사용하여 기능 브랜치의 존재를 병합 커밋으로 DAG에 기록하고, 리버트나 트래킹을 용이하게 한다.

DAG의 구조나 해시 함수의 원리 등 수학적, 아키텍처적 배경을 이해함으로써, Git 명령어는 단순한 암기에서 “의도를 가진 이력 설계"로 승화됩니다. 리베이스의 황금률을 지키면서 상황에 맞는 최적의 명령어를 선택하여, 팀 전체가 읽기 쉽고 유지 보수하기 편한 깔끔한 커밋 이력을 구축해 나갑시다.

GitHub Actions를 사용한 C++ 프로젝트의 CI/CD 파이프라인 구축

Sat, 12 Sep 2026 18:00:00 +0900

GitHub Actions를 사용한 C++ 프로젝트의 CI/CD 파이프라인 구축: 완전 가이드

현대 소프트웨어 개발 패러다임에서 지속적 통합(Continuous Integration: CI)과 지속적 제공/배포(Continuous Delivery/Deployment: CD)는 애자일한 개발 프로세스와 고품질 소프트웨어를 유지하는 데 필수적인 요소입니다. 수많은 프로그래밍 언어가 존재하지만, C++에서의 CI/CD 파이프라인 구축은 다른 언어(예: Python, JavaScript, Go 등)에 비해 독특한 어려움과 복잡성을 수반합니다.

본 문서에서는 GitHub Actions를 활용하여 C++ 프로젝트를 위한 견고하고 실용적인 CI/CD 파이프라인을 처음부터 구축하는 방법을 매우 상세하게 설명합니다. 크로스 플랫폼(Windows, Linux, macOS)에서의 매트릭스 빌드, CMake를 이용한 빌드 시스템 통합, CTest를 사용한 자동 테스트, 정적·동적 분석 자동화, 커버리지 측정, 그리고 GitHub Releases를 통한 컴파일된 바이너리의 자동 전달까지 모든 실전 기술을 망라합니다.

1. C++ 프로젝트에서 CI/CD의 의미와 특유의 과제

웹 애플리케이션이나 스크립트 언어를 사용한 개발에서는 단일 Docker 컨테이너에서의 테스트 및 빌드로 충분한 경우가 대부분입니다. 그러나 C++는 네이티브로 컴파일되는 언어이며, 실행 환경의 하드웨어 아키텍처나 운영 체제에 강하게 의존합니다.

C++ 프로젝트에 CI/CD를 도입할 때 직면하는 주요 과제는 다음과 같습니다.

플랫폼의 다양성: Windows, Linux, macOS와 같이 다른 OS마다 API(Windows API, POSIX 등)가 다릅니다. 개발자의 로컬 환경(예: macOS)에서 동작하더라도 Linux나 Windows에서 컴파일 오류가 발생하는 일은 일상다반사입니다.
컴파일러의 차이: Microsoft Visual C++ (MSVC), GNU Compiler Collection (GCC), Clang과 같은 주요 컴파일러는 C++ 표준(C++17, C++20, C++23)의 구현 정도나 해석, 경고의 엄격함이 다릅니다.
빌드 시간: 대규모 C++ 프로젝트에서는 빌드에 수십 분에서 수 시간이 걸리는 일도 드물지 않습니다. CI 환경에서는 제한된 컴퓨팅 리소스로 효율적으로 빌드하기 위한 캐시 전략과 병렬화가 필요합니다.
의존성 관리: C++에는 npm이나 pip 같은 절대적인 표준 패키지 관리자가 존재하지 않습니다. vcpkg, Conan 또는 CMake의 FetchContent 등을 사용하여 CI 환경에서 매번 올바르게 라이브러리를 해결해야 합니다.
메모리 관리와 미정의 동작: 포인터 조작이나 수동 메모리 관리가 수반되므로, 단순한 로직 테스트뿐만 아니라 메모리 누수나 미정의 동작(Undefined Behavior)의 감지도 자동화해야 합니다.

이러한 과제를 해결하기 위해서는 다양한 OS 가상 머신을 온디맨드로 프로비저닝할 수 있고, 복잡한 워크플로우를 코드로 정의(Configuration as Code)할 수 있는 GitHub Actions가 최적의 솔루션이 됩니다.

2. CI/CD 파이프라인의 아키텍처 개요

이제 구축할 CI/CD 파이프라인의 전체적인 모습을 시각화해 보겠습니다. 아래의 Mermaid 시퀀스 다이어그램은 코드 Push부터 배포까지의 워크플로우를 보여줍니다.

sequenceDiagram
participant Dev as "개발자"
participant Repo as "GitHub 저장소"
participant Action as "GitHub Actions CI/CD"
participant Rel as "GitHub Releases"
Dev->>Repo: "브랜치 Push / PR 열기"
Repo->>Action: "CI 워크플로우 트리거"
activate Action
Action->>Action: "린트 및 정적 분석 (Clang-Tidy)"
rect rgb(200, 220, 240)
note right of Action: "크로스 플랫폼 매트릭스 빌드"
Action->>Action: "Ubuntu 빌드 (GCC/Clang)"
Action->>Action: "Windows 빌드 (MSVC)"
Action->>Action: "macOS 빌드 (Apple Clang)"
end
Action->>Action: "CTest 실행 (ASAN/UBSAN 포함)"
Action->>Action: "커버리지 리포트 생성"
alt "태그가 Push된 경우 (예: v1.0.0)"
Action->>Action: "CPack으로 바이너리 패키징"
Action->>Rel: "ZIP/Tarball을 Release에 업로드"
end
deactivate Action
Repo-->>Dev: "CI 상태 보고 (성공/실패)"

이 아키텍처에서는 Pull Request 단계에서는 빠른 피드백(정적 분석 및 빌드·테스트)을 제공하고, 버전 태그가 부여된 시점에서 결과물의 패키징 및 배포를 수행합니다.

3. 모던 CMake를 사용한 프로젝트 설정

훌륭한 CI 파이프라인의 기반이 되는 것은 견고한 빌드 시스템입니다. C++의 사실상 표준인 CMake를 사용합니다. 여기에서는 “모던 CMake"라고 불리는 타겟 지향적인 접근 방식을 채택합니다.

프로젝트의 디렉토리 구조를 다음과 같이 가정합니다.

1
2
3
4
5
6
7
8
9


my_cpp_project/
├── CMakeLists.txt
├── src/
│ ├── main.cpp
│ ├── calculator.cpp
│ └── calculator.h
└── tests/
 ├── CMakeLists.txt
 └── test_calculator.cpp

루트의 CMakeLists.txt 설정 예시입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


cmake_minimum_required(VERSION 3.20)
project(MyCppProject VERSION 1.0.0 LANGUAGES CXX)

# C++ 표준 설정
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF) # 컴파일러 고유의 확장을 비활성화하여 이식성을 높임

# 컴파일러 경고 엄격화
function(set_project_warnings target_name)
 if(MSVC)
 target_compile_options(${target_name} PRIVATE /W4 /WX)
 else()
 target_compile_options(${target_name} PRIVATE -Wall -Wextra -Wpedantic -Werror)
 endif()
endfunction()

# 라이브러리 타겟 생성
add_library(CalculatorLib src/calculator.cpp)
target_include_directories(CalculatorLib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
set_project_warnings(CalculatorLib)

# 실행 파일 타겟 생성
add_executable(MyApplication src/main.cpp)
target_link_libraries(MyApplication PRIVATE CalculatorLib)
set_project_warnings(MyApplication)

# 테스트 활성화
enable_testing()
add_subdirectory(tests)

# 설치 규칙 정의 (CPack용)
include(GNUInstallDirs)
install(TARGETS MyApplication CalculatorLib
 RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
 ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

# CPack을 통한 패키징 설정
set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
set(CPACK_GENERATOR "ZIP;TGZ")
if(WIN32)
 set(CPACK_GENERATOR "ZIP")
endif()
include(CPack)

중요한 포인트:

CMAKE_CXX_EXTENSIONS OFF: GNU 확장 등 비표준 기능에 대한 의존성을 방지하고 크로스 플랫폼성을 보장합니다.
경고 엄격화 (-Werror / /WX): CI 환경에서 컴파일러 경고를 에러로 취급하여 코드 품질을 강제로 높게 유지합니다.
GNUInstallDirs: OS별 표준 설치 경로(/usr/local/bin이나 C:\Program Files 등)를 자동으로 해결합니다.

4. GitHub Actions의 기초와 매트릭스 전략

GitHub Actions는 .github/workflows/ 디렉토리 내의 YAML 파일로 구성됩니다. C++ 프로젝트에서 가장 강력한 기능이 “매트릭스 전략(Matrix Strategy)“입니다. 이를 통해 OS와 컴파일러의 조합을 동적으로 생성하고 병렬로 실행할 수 있습니다.

graph TD
A["워크플로우 트리거"] --> B["매트릭스 작업 평가"]
B --> C["Ubuntu 22.04 (GCC 12)"]
B --> D["Ubuntu 22.04 (Clang 15)"]
B --> E["Windows Server 2022 (MSVC)"]
B --> F["macOS 14 (Apple Clang)"]

아래에 매트릭스 빌드의 기본이 되는 YAML의 작업 정의를 보여줍니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


jobs:
 build:
 name: "Build & Test [${{ matrix.os }} - ${{ matrix.compiler }}]"
 runs-on: ${{ matrix.os }}
 strategy:
 fail-fast: false # 하나의 작업이 실패해도 다른 OS의 빌드를 계속함
 matrix:
 include:
 - os: ubuntu-latest
 compiler: gcc
 c_compiler: gcc
 cpp_compiler: g++
 - os: ubuntu-latest
 compiler: clang
 c_compiler: clang
 cpp_compiler: clang++
 - os: windows-latest
 compiler: msvc
 c_compiler: cl
 cpp_compiler: cl
 - os: macos-latest
 compiler: apple-clang
 c_compiler: clang
 cpp_compiler: clang++

fail-fast: false는 매우 중요합니다. 예를 들어 Linux 특유의 API를 잘못 사용한 경우, Ubuntu의 빌드는 실패하지만 Windows의 빌드는 성공하는지 여부도 동시에 확인하고 싶기 때문입니다.

5. 빌드 비용과 암달의 법칙을 이용한 병렬 처리 최적화

클라우드 환경에서의 CI/CD는 시간과의 싸움이며, 빌드 시간은 그대로 개발자의 대기 시간 및 운영 비용과 직결됩니다. 여기서 빌드 시간 최적화에 대해 컴퓨터 과학의 “암달의 법칙(Amdahl’s Law)“을 사용하여 수학적으로 접근해 보겠습니다.

암달의 법칙은 프로그램 중 병렬화 가능한 부분의 비율을 $P$라고 할 때, $N$개의 프로세서를 사용했을 때의 이론상 최대 속도 향상률 $S(N)$을 다음과 같이 정의합니다.

$$ S(N) = \frac{1}{(1 - P) + \frac{P}{N}} $$

C++ 빌드 프로세스에서 소스 코드의 각 번역 단위(Translation Unit: .cpp 파일) 컴파일은 완전히 독립적이며 병렬화가 가능합니다. 반면, CMake 구성이나 최종 바이너리 링크 단계는 기본적으로 직렬 실행(병렬화 불가)이 됩니다.

만약 프로젝트의 전체 빌드 시간 중 80%가 컴파일 단계($P = 0.8$), 20%가 직렬 단계($1 - P = 0.2$)라고 가정합시다. GitHub Actions의 표준 러너(Linux)는 2코어(스레드)를 제공합니다. 따라서 $N = 2$인 경우:

$$ S(2) = \frac{1}{0.2 + \frac{0.8}{2}} = \frac{1}{0.2 + 0.4} = \frac{1}{0.6} \approx 1.67 $$

2코어를 사용하는 것만으로 약 1.67배의 속도 향상을 얻을 수 있습니다. 이를 실현하기 위해서는 CMake 빌드 명령어에 --parallel 옵션을 지정하는 것이 필수적입니다.

1
2


 - name: "Build Project"
 run: cmake --build build --config Release --parallel 2

더 나아가 비용 계산도 고려합니다. GitHub Actions의 이용 비용 $C_{total}$은 작업의 실행 시간 $T_i$와 러너의 단가 $R_i$의 곱의 총합입니다.

$$ C_{total} = \sum_{i=1}^{M} \left( T_i \times R_i \right) $$

빌드 시간을 단축하는 것은 피드백 루프를 가속화할 뿐만 아니라, 프로젝트의 운영 비용(특히 비공개 저장소의 경우)을 직접적으로 절감하는 결과로 이어집니다. 더 빠른 속도를 원한다면 ccache를 도입하여 컴파일 결과를 캐시하는 방법이 효과적입니다.

6. 자동 테스트와 새니타이저(Sanitizers)의 통합

C++에서 버그를 미연에 방지하기 위해서는 단위 테스트 외에 메모리 누수나 미정의 동작을 실행 시에 감지하는 “새니타이저"의 도입을 강력히 권장합니다. Google이 개발한 AddressSanitizer (ASAN) 및 UndefinedBehaviorSanitizer (UBSAN)를 사용합니다.

CMake에서 새니타이저를 활성화하는 옵션을 추가합니다.

1
2
3
4
5


option(ENABLE_SANITIZERS "Enable ASAN and UBSAN" OFF)
if(ENABLE_SANITIZERS AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
 add_compile_options(-fsanitize=address,undefined -fno-omit-frame-pointer)
 add_link_options(-fsanitize=address,undefined)
endif()

CI 파이프라인의 Ubuntu 작업에서 이 옵션을 활성화하여 테스트를 실행합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 - name: "Configure CMake"
 env:
 CC: ${{ matrix.c_compiler }}
 CXX: ${{ matrix.cpp_compiler }}
 run: >
 cmake -B build
 -DCMAKE_BUILD_TYPE=Release
 -DENABLE_SANITIZERS=${{ matrix.os == 'ubuntu-latest' && 'ON' || 'OFF' }}

 - name: "Run CTest"
 working-directory: build
 env:
 ASAN_OPTIONS: "detect_leaks=1:symbolize=1"
 UBSAN_OPTIONS: "print_stacktrace=1"
 run: ctest --build-config Release --output-on-failure --parallel 2

테스트 실행에는 ctest 명령어를 사용합니다. --output-on-failure를 지정하여 실패한 테스트의 자세한 로그만 CI 출력에 표시하여 로그가 비대해지는 것을 방지합니다.

7. 커버리지(코드 커버리지) 측정

테스트가 얼마나 많은 코드를 커버하고 있는지 시각화하는 것은 품질 보증에 있어 중요합니다. Linux 환경(GCC)을 이용하여 gcov 및 lcov로 커버리지를 측정합니다.

먼저 CMake에서 커버리지 측정용 컴파일 플래그를 설정합니다.

1
2
3
4
5


option(ENABLE_COVERAGE "Enable coverage reporting" OFF)
if(ENABLE_COVERAGE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
 add_compile_options(--coverage -O0 -g)
 add_link_options(--coverage)
endif()

커버리지 측정용 독립적인 작업을 GitHub Actions에 정의합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 coverage:
 name: "Test Coverage Analysis"
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: "Install lcov"
 run: sudo apt-get update && sudo apt-get install -y lcov

 - name: "Configure CMake for Coverage"
 run: cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON

 - name: "Build & Test"
 run: |
 cmake --build build --parallel 2
 cd build && ctest --output-on-failure

 - name: "Generate lcov Report"
 working-directory: build
 run: |
 lcov --capture --directory . --output-file coverage.info
 lcov --remove coverage.info '/usr/*' '*_deps/*' '*tests/*' --output-file coverage.info
 
 - name: "Upload Coverage to Codecov"
 uses: codecov/codecov-action@v3
 with:
 files: build/coverage.info

lcov --remove 명령어를 사용하여 시스템 헤더나 서드파티 라이브러리, 테스트 코드 자체를 커버리지 측정 대상에서 제외합니다. 이를 통해 프로젝트 고유의 소스 코드의 순수한 커버리지를 얻을 수 있습니다.

8. GitHub Releases를 통한 바이너리 자동 배포 (CD)

CI/CD의 “CD” 부분을 구축합니다. 개발자가 Git에서 버전 태그(예: v1.2.0)를 부여하여 푸시했을 때, 자동으로 각 OS용 실행 가능한 바이너리를 컴파일하고 ZIP이나 Tarball로 패키징하여 GitHub Releases에 업로드합니다.

이 단계에서는 CMake에 포함된 패키징 도구 CPack을 이용합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 - name: "Package Application (CPack)"
 if: startsWith(github.ref, 'refs/tags/v')
 working-directory: build
 run: cpack -C Release -V

 - name: "Upload Release Assets"
 if: startsWith(github.ref, 'refs/tags/v')
 uses: softprops/action-gh-release@v1
 with:
 files: |
 build/*.tar.gz
 build/*.zip
 build/*.sh
 build/*.exe
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

이 설정을 통해 git tag v1.0.0과 git push origin v1.0.0을 실행하는 것만으로, Windows 사용자용으로는 ZIP 파일이, Linux/macOS 사용자용으로는 Tarball이 수동 개입 없이 자동으로 릴리스 페이지에 공개됩니다. 이것은 사용자에게 소프트웨어를 제공하는 데 있어 매우 강력한 기능입니다.

9. 완전한 Workflow YAML 파일

지금까지 설명한 모든 요소를 통합한, 견고하고 실용적인 .github/workflows/main.yml의 완전한 코드를 아래에 보여줍니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107


name: "C++ CI/CD Pipeline"

on:
 push:
 branches: [ "main", "develop" ]
 tags: [ "v*.*.*" ]
 pull_request:
 branches: [ "main" ]

env:
 BUILD_TYPE: Release

jobs:
 build-and-test:
 name: "Build [${{ matrix.os }} | ${{ matrix.compiler }}]"
 runs-on: ${{ matrix.os }}
 strategy:
 fail-fast: false
 matrix:
 include:
 - os: ubuntu-latest
 compiler: gcc
 c_compiler: gcc
 cpp_compiler: g++
 - os: ubuntu-latest
 compiler: clang
 c_compiler: clang
 cpp_compiler: clang++
 - os: windows-latest
 compiler: msvc
 c_compiler: cl
 cpp_compiler: cl
 - os: macos-latest
 compiler: apple-clang
 c_compiler: clang
 cpp_compiler: clang++

 steps:
 - name: "Checkout Repository"
 uses: actions/checkout@v4

 - name: "Configure CMake"
 env:
 CC: ${{ matrix.c_compiler }}
 CXX: ${{ matrix.cpp_compiler }}
 run: >
 cmake -B build
 -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }}
 -DENABLE_SANITIZERS=${{ matrix.os == 'ubuntu-latest' && 'ON' || 'OFF' }}

 - name: "Build Project"
 run: cmake --build build --config ${{ env.BUILD_TYPE }} --parallel 2

 - name: "Run Unit Tests (CTest)"
 working-directory: build
 env:
 ASAN_OPTIONS: "detect_leaks=1:symbolize=1"
 UBSAN_OPTIONS: "print_stacktrace=1"
 run: ctest --build-config ${{ env.BUILD_TYPE }} --output-on-failure --parallel 2

 - name: "Package with CPack"
 if: startsWith(github.ref, 'refs/tags/v')
 working-directory: build
 run: cpack -C ${{ env.BUILD_TYPE }}

 - name: "Create GitHub Release and Upload Assets"
 if: startsWith(github.ref, 'refs/tags/v')
 uses: softprops/action-gh-release@v1
 with:
 files: |
 build/*.tar.gz
 build/*.zip
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

 coverage:
 name: "Code Coverage Analysis"
 runs-on: ubuntu-latest
 if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
 steps:
 - name: "Checkout Repository"
 uses: actions/checkout@v4

 - name: "Install lcov"
 run: sudo apt-get update && sudo apt-get install -y lcov

 - name: "Configure CMake for Coverage"
 run: cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON

 - name: "Build Project"
 run: cmake --build build --parallel 2

 - name: "Run Tests"
 working-directory: build
 run: ctest --output-on-failure

 - name: "Generate lcov Report"
 working-directory: build
 run: |
 lcov --capture --directory . --output-file coverage.info
 lcov --remove coverage.info '/usr/*' '*_deps/*' '*tests/*' --output-file coverage.info
 
 - name: "Upload Coverage to Codecov"
 uses: codecov/codecov-action@v3
 with:
 files: build/coverage.info
 fail_ci_if_error: false

10. 더 높은 수준의 CI/CD를 향하여 (정적 분석과 포맷팅)

여기서는 자세한 설명은 생략하지만, 실제 운용에 있어서는 추가적인 품질 보증 도구를 파이프라인에 통합하는 것을 권장합니다.

Clang-Format 강제: 코드 리뷰의 부담을 줄이기 위해 clang-format을 통한 코드 스타일 검사를 CI에 통합하고, 포맷 규칙을 위반하는 경우 파이프라인을 실패시킵니다.
정적 분석 (Clang-Tidy): 컴파일러 경고만으로는 막을 수 없는 잠재적 버그나 비효율적인 코드(불필요한 복사 등)를 감지하기 위해, clang-tidy를 CMake에 통합하고 CI상에서 실행합니다.
vcpkg / Conan 캐시 활용: 서드파티 라이브러리를 다수 사용하는 경우, 의존성 빌드에 엄청난 시간이 소요됩니다. GitHub Actions의 actions/cache를 이용하여 vcpkg의 설치된 디렉토리나 Conan의 캐시를 유지함으로써 빌드 시간을 획기적으로 줄일 수 있습니다.

결론

C++ 프로젝트에서 CI/CD 파이프라인 구축은 플랫폼 의존성이나 빌드 도구의 복잡성 때문에 언뜻 보기에 진입 장벽이 높게 느껴집니다. 하지만 GitHub Actions, 모던 CMake, 그리고 CTest/CPack 생태계를 올바르게 조합함으로써, 매우 강력하고 자동화된 개발 흐름을 얻을 수 있습니다.

본 문서에서 설명한 매트릭스 전략을 이용한 크로스 플랫폼 검증, 새니타이저를 이용한 런타임 버그 감지, 커버리지 측정, 그리고 GitHub Releases로의 자동 배포는 상용 수준의 오픈 소스 프로젝트에서도 널리 채택하고 있는 모범 사례입니다.

자동화된 CI/CD 파이프라인은 개발자가 “버그 찾기"이나 “수동 빌드 및 릴리스 작업"에 쏟는 시간을 최소화하고, 본연의 창조적인 코딩 활동에 집중하기 위한 최강의 무기가 됩니다. 여러분의 C++ 프로젝트에도 적극 도입하여, 애자일하고 안심할 수 있는 개발 라이프를 실현하시기 바랍니다.

Cloudflare Pages나 GitHub Pages로 Hugo 블로그를 무료로, 초고속으로 공개하는 방법

Sat, 12 Sep 2026 12:00:00 +0900

웹사이트나 블로그를 운영하는 데 있어서 표시 속도(퍼포먼스), 운영 비용, 그리고 보안은 매우 중요한 요소입니다. 예전에는 WordPress와 같은 동적 CMS(Content Management System)와 렌탈 서버의 조합이 주류를 이루었지만, 현재는 ‘Jamstack’이라고 불리는 아키텍처가 큰 주목을 받고 있습니다. 그 중에서도 Go 언어로 만들어진 초고속 정적 사이트 생성기(SSG)인 ‘Hugo’와, Cloudflare Pages나 GitHub Pages 같은 모던 호스팅 서비스를 조합하면 완전 무료이면서 초고속인 블로그 환경을 구축할 수 있습니다.

이 글에서는 Hugo를 사용한 정적 사이트를 Cloudflare Pages나 GitHub Pages에 공개하기 위한 구체적인 절차, 각 플랫폼의 아키텍처 차이, GitHub Actions를 이용한 CI/CD(지속적 통합/지속적 배포) 구축, DNS 최적화, 캐시 전략, 그리고 프라이버시를 고려한 접속 분석 도입에 이르기까지 기술적인 관점에서 매우 깊이 있게 설명합니다.

1. 정적 사이트 생성기(SSG)와 Jamstack의 기초

1.1 왜 정적 사이트인가?

기존의 동적 CMS(예: WordPress)는 사용자로부터 요청이 있을 때마다 데이터베이스(MySQL 등)에 쿼리를 실행하고, 서버 사이드(PHP 등)에서 HTML을 동적으로 생성하여 반환합니다. 이 방식은 유연성이 높은 반면, 트래픽의 급증(이른바 화제성 집중이나 DDoS 공격)에 대한 내성이 낮아 캐시 서버(Redis나 Varnish)를 전면에 두는 등 인프라 구성이 복잡해지기 쉽습니다.

반면, Jamstack(JavaScript, APIs, and Markup) 아키텍처를 채택한 정적 사이트 생성기(SSG)에서는 사전에(빌드 시에) 모든 HTML 파일, CSS, JavaScript를 생성해 둡니다. 사용자의 요청에 대해서는 이미 생성된 정적 파일을 웹 서버(또는 CDN)가 그대로 반환하기만 하므로, 압도적인 고속성과 견고한 보안을 실현할 수 있습니다.

1.2 Hugo의 우위성

SSG에는 Next.js, Gatsby, Jekyll, Astro 등 다양한 선택지가 있지만, Hugo의 가장 큰 특징은 바로 빌드 속도입니다. Go 언어의 병행 처리 혜택 덕분에, 수천에서 수만 페이지의 사이트라도 불과 몇 초 만에 빌드가 완료됩니다. 이는 CI/CD 파이프라인에서의 대기 시간을 대폭 줄여주며, 개발자 경험(DX: Developer Experience) 향상과 직결됩니다.

2. 호스팅 서비스의 아키텍처 비교

Hugo로 생성한 정적 파일을 어디에 호스팅할 것인지가 다음 과제입니다. 대표적인 선택지로 Cloudflare Pages, GitHub Pages, 그리고 Netlify를 들 수 있는데, 각각 배후에 있는 네트워크 아키텍처가 다릅니다.

2.1 CDN과 엣지 컴퓨팅

이러한 플랫폼들은 모두 글로벌하게 분산된 CDN(Content Delivery Network)을 이용하여 콘텐츠를 전송합니다. 하지만 단순한 정적 파일의 캐싱뿐만 아니라, ‘엣지 컴퓨팅’을 통해 요청 라우팅이나 헤더 수정을 사용자와 가장 가까운 PoP(Point of Presence)에서 실행할 수 있는지가 차별화 요소가 되고 있습니다.

graph TD
A["사용자 (도쿄)"] -->|Low Latency| B["엣지 노드 (NRT)"]
C["사용자 (뉴욕)"] -->|Low Latency| D["엣지 노드 (EWR)"]
E["사용자 (런던)"] -->|Low Latency| F["엣지 노드 (LHR)"]
B --> G["오리진 스토리지 / 오브젝트 스토어"]
D --> G
F --> G

2.2 GitHub Pages

GitHub Pages는 GitHub 저장소에서 직접 HTML, CSS, JavaScript 파일을 공개할 수 있는 서비스입니다. 그 배후에는 Fastly 같은 CDN이 이용되고 있어 충분한 퍼포먼스를 발휘합니다. 단, 헤더의 커스터마이즈(예: Cache-Control이나 보안 헤더 설정)에 제약이 있는 데다, 리다이렉트 설정에는 HTML의 meta refresh나 Jekyll의 플러그인에 의존하는 등 순수한 인프라로서의 기능은 약간 부족한 편입니다.

2.3 Cloudflare Pages

Cloudflare Pages는 Cloudflare가 자랑하는 세계 최대 규모의 Anycast 네트워크(275개 이상의 도시에 전개) 위에 구축된 정적 사이트 호스팅 서비스입니다. HTTP/3(QUIC)의 기본 지원, 이미지 최적화, 엣지 함수(Cloudflare Workers)의 통합 등 압도적인 퍼포먼스 튜닝이 가능합니다. 또한 대역폭에 대한 과금이 없어, 아무리 트래픽이 급증해도 무료로 운영할 수 있다는 점이 큰 장점입니다.

2.4 Netlify

Netlify는 Jamstack의 선구자적인 존재로, 폼 기능, 인증(Identity), 서버리스 함수 등을 통합한 올인원 DX를 제공합니다. 그러나 무료 제공량의 대역폭(월간 100GB)을 초과하면 고액의 종량제 과금이 발생하므로, 이미지나 동영상을 많이 사용하는 블로그에서는 비용 관리에 주의가 필요합니다.

3. 퍼포먼스와 지연 시간의 이론적 계산 (LaTeX에 의한 수리 모델)

웹 퍼포먼스를 평가하는 데 있어서 지연 시간(Latency)의 감소는 가장 중요한 지표입니다. CDN(엣지)을 이용함으로써 오리진 서버에 직접 접속할 때와 비교하여 지연 시간이 얼마나 줄어드는지를 모델화해 봅시다.

사용자의 요청이 캐시에 적중할 확률을 ‘캐시 적중률(Cache Hit Ratio)‘이라 하고, $C$ 로 둡니다. $0 \le C \le 1$ 입니다. 오리진 서버까지의 지연 시간을 $L_{origin}$, 가장 가까운 엣지 노드까지의 지연 시간을 $L_{edge}$ 라고 합니다.

새로운 평균 지연 시간 $L_{new}$ 는 다음의 기댓값으로 계산됩니다.

$$ L_{new} = C \times L_{edge} + (1 - C) \times (L_{edge} + L_{origin}) $$

이 식을 간략화하면 다음과 같습니다.

$$ L_{new} = L_{edge} + (1 - C) \times L_{origin} $$

예를 들어, 도쿄의 사용자가 미국 동부 해안(뉴욕)에 있는 오리진 서버에 접속할 경우, 광섬유의 물리적인 거리와 라우터에서의 처리 지연을 고려하면 $L_{origin}$ 은 약 200 ms 정도가 됩니다. 반면, Cloudflare와 같은 CDN을 이용하면 도쿄의 엣지 노드에 연결할 수 있으므로 $L_{edge}$ 는 약 10 ms 정도로 단축됩니다.

만약 캐시 적중률이 $C = 0.95$ (95%)라고 가정하면,

$$ L_{new} = 10 + (1 - 0.95) \times 200 = 10 + 0.05 \times 200 = 10 + 10 = 20 \text{ ms} $$

이처럼 CDN 도입을 통해 평균 지연 시간을 210 ms에서 20 ms로 극적으로(약 90%) 줄이는 것이 가능해집니다.

4. GitHub Actions를 이용한 CI/CD 파이프라인 구축

Hugo 블로그의 업데이트 프로세스를 자동화하기 위해, GitHub Actions를 이용한 CI/CD 파이프라인을 구축합니다. 이를 통해 로컬에서 Markdown 글을 작성하고 git push 하기만 하면, 자동으로 빌드가 실행되어 Cloudflare Pages나 GitHub Pages에 배포됩니다.

다음의 시퀀스 다이어그램은 글을 Push한 후 사용자에게 전송될 때까지의 전체 흐름을 보여줍니다.

sequenceDiagram
participant U as "사용자 (작성자)"
participant G as "GitHub 저장소"
participant A as "GitHub Actions"
participant C as "Cloudflare Pages"
participant V as "방문자"
U->>G: "git push origin main"
G->>A: "Push 이벤트 트리거"
A->>A: "체크아웃 및 Hugo 설정"
A->>A: "hugo --minify (빌드)"
A->>C: "Cloudflare Pages에 배포 (직접 업로드)"
C-->>A: "배포 URL (성공)"
V->>C: "웹 페이지 요청"
C-->>V: "캐시된 HTML 반환 (엣지)"

4.1 Cloudflare Pages를 위한 배포 설정 (Direct Upload)

Cloudflare Pages에는 GitHub 저장소를 연동시켜 Cloudflare의 인프라 위에서 빌드하는 방법과, GitHub Actions에서 빌드한 정적 파일을 ‘Direct Upload(직접 업로드)‘하는 방법이 있습니다. Hugo의 버전 관리를 더 엄격하게 하고 다른 작업(테스트나 이미지 최적화 등)과 연동하고 싶다면, GitHub Actions에서 빌드하고 Direct Upload 하는 방식을 추천합니다.

다음은 Cloudflare Pages에 배포하기 위한 .github/workflows/deploy.yml 의 실전 예시입니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


name: "Deploy Hugo site to Cloudflare Pages"

on:
 push:
 branches:
 - "main"
 workflow_dispatch:

jobs:
 build-and-deploy:
 runs-on: "ubuntu-latest"
 steps:
 - name: "Checkout repository"
 uses: "actions/checkout@v4"
 with:
 submodules: "recursive"
 fetch-depth: 0

 - name: "Setup Hugo"
 uses: "peaceiris/actions-hugo@v3"
 with:
 hugo-version: "0.125.0"
 extended: true

 - name: "Build Hugo Site"
 run: "hugo --minify --gc"
 env:
 HUGO_ENVIRONMENT: "production"

 - name: "Deploy to Cloudflare Pages"
 uses: "cloudflare/pages-action@v1"
 with:
 apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 projectName: "your-project-name"
 directory: "public"
 gitHubToken: ${{ secrets.GITHUB_TOKEN }}
 branch: "main"

이 파이프라인에서는 --minify 옵션으로 HTML/CSS/JS를 축소하고, --gc 로 불필요한 파일을 삭제하고 있습니다. 이것들은 퍼포먼스 최적화의 기본입니다.

5. DNS 설정 깊게 파고들기: 커스텀 도메인과 CNAME / ALIAS 레코드

독자 도메인(예: kenji.blog)을 이용할 경우, DNS(Domain Name System)의 적절한 설정이 필수적입니다.

5.1 CNAME 레코드의 제약과 Zone Apex

보통 서브 도메인(예: www.kenji.blog)을 외부 서비스로 연결할 경우에는 CNAME 레코드를 이용합니다. 그러나 DNS의 사양(RFC 1034)에 따라 루트 도메인(Zone Apex, 네이키드 도메인이라고도 불림. 예: kenji.blog)에는 CNAME 레코드를 설정할 수 없습니다. 이는 Zone Apex에는 SOA(Start of Authority) 레코드나 NS(Name Server) 레코드, MX(Mail Exchange) 레코드가 반드시 존재해야 하며, CNAME은 다른 리소스 레코드와 공존할 수 없다는 규칙이 있기 때문입니다.

5.2 해결책: ALIAS / ANAME / CNAME Flattening

이 문제를 해결하기 위해, 모던 DNS 제공업체들은 자체적인 확장 기능을 제공하고 있습니다.

ALIAS / ANAME 레코드: DNS 서버 측에서 동적으로 이름 확인을 수행하여, 최종적인 A 레코드(IP 주소)를 클라이언트에 반환합니다. Amazon Route 53 등이 지원하고 있습니다.
CNAME Flattening: Cloudflare가 제공하는 기능입니다. Zone Apex에 CNAME을 설정한 것처럼 작동하면서, Cloudflare의 권한(Authoritative) DNS 서버가 자동으로 확인한 IP 주소들(A 레코드 및 AAAA 레코드)을 클라이언트에게 투명하게 반환합니다.

Cloudflare Pages를 이용할 경우, 도메인의 네임 서버를 Cloudflare에 위임하고, 이 ‘CNAME Flattening’을 활용하는 것이 가장 매끄럽고 고성능인 구성이 됩니다.

6. 캐시 전략과 HTTP 헤더 제어

정적 사이트의 고속화에 있어서 또 하나의 핵심이 되는 것은 ‘캐시 전략’입니다. Cloudflare Pages에서는 생성된 파일(_headers 파일)을 이용하여, HTTP 응답 헤더를 세밀하게 제어할 수 있습니다.

6.1 엣지 캐시(Edge Cache) vs 브라우저 캐시(Browser Cache)

캐시에는 크게 나누어 CDN 측에서 유지되는 ‘엣지 캐시’와 사용자의 브라우저에 저장되는 ‘브라우저 캐시’ 2종류가 있습니다.

정적 파일(이미지, CSS, JS 등 파일명에 해시가 포함된 것)은 브라우저 측에 장기간 캐싱시키는 것이 이상적입니다. 반면, HTML 파일은 업데이트를 즉시 반영하기 위해 브라우저 캐시를 짧게(혹은 무효화) 하고, 엣지 캐시로 처리하는 구성이 일반적입니다.

Cloudflare Pages에서의 _headers 설정 예시:

1
2
3
4
5
6
7
8
9


# HTML 파일은 브라우저 캐시를 하지 않고, 매번 검증한다
/*.html
 Cache-Control: public, max-age=0, must-revalidate

# 에셋 파일(CSS/JS/이미지)은 1년간 브라우저에 캐시한다
/assets/*
 Cache-Control: public, max-age=31536000, immutable
/img/*
 Cache-Control: public, max-age=31536000, immutable

6.2 대역폭 비용 절감 계산식

적절한 캐시 헤더를 설정함으로써 서버(엣지)로부터의 데이터 전송량을 대폭 줄일 수 있습니다. 월간 대역폭 비용 $Cost$ 는 각 리소스의 전송량 $B_i$, 캐시 적중률 $C_i$, 그리고 대역폭 단가 $R$ 에 의해 다음과 같은 모델로 나타낼 수 있습니다.

$$ Cost = \sum_{i=1}^{n} \left( B_i \times (1 - C_i) \times R \right) $$

Cloudflare는 다운로드 전송량이 무료($R = 0$)이므로 직접적인 금전적 비용은 $0$ 이 됩니다. 그러나 GitHub Pages 등 다른 인프라를 병용하는 경우나 AWS 구성을 백엔드로 삼는 경우에는, 이 캐시 적중률 $C_i$ 를 극대화하는 것이 인프라 비용 절감의 핵심이 됩니다.

7. 프라이버시와 퍼포먼스를 양립하는 접속 분석

블로그를 운영하는 데 있어서, 얼마나 많은 사용자가 방문하고 있는지를 알기 위한 접속 분석(Web Analytics)은 필수적입니다. 오랫동안 Google Analytics(GA4)가 사실상의 표준(De facto standard)이었지만, 최근의 프라이버시 보호 흐름(GDPR, CCPA)이나 서드파티 쿠키 폐지에 따라 상황이 변하고 있습니다.

7.1 웹 퍼포먼스에 미치는 영향

Google Analytics(구체적으로는 gtag.js 나 Google Tag Manager)를 도입하면, 수많은 외부 스크립트의 로딩과 실행이 발생하여 퍼포먼스(특히 TTFB나 메인 스레드 차단 시간)에 악영향을 미칩니다.

사이트의 로드 시간을 다음과 같이 분해해서 생각해 봅시다.

pie title "일반적인 사이트 로딩 시간 분석"
"TTFB (첫 바이트 도달 시간)" : 15
"콘텐츠 다운로드 (HTML/CSS)" : 20
"DOM 파싱 및 렌더링" : 45
"분석 및 서드파티 JS" : 20

서드파티의 JS 분석 도구는 전체 로딩 시간의 약 20%~30%를 차지하는 일도 드물지 않습니다.

7.2 Cloudflare Web Analytics의 도입

그래서 주목받고 있는 것이 Cloudflare Web Analytics나 Plausible Analytics 같은, 쿠키를 사용하지 않는(Cookieless) 프라이버시 퍼스트 접속 분석입니다.

Cloudflare Web Analytics는 매우 가벼운 JavaScript 스니펫을 삽입하기만 하면 작동하며, 쿠키를 발행하지 않기 때문에 번거로운 쿠키 동의 배너(Cookie Consent Banner)를 설치할 필요가 없습니다.

Hugo에서의 구현도 매우 간단합니다. layouts/partials/head.html 이나 layouts/partials/analytics.html 에 제공받은 스니펫을 추가하기만 하면 됩니다.

1
2
3
4
5


{{ if eq hugo.Environment "production" }}
<!-- Cloudflare Web Analytics -->
<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "YOUR_CLOUDFLARE_BEACON_TOKEN"}'></script>
<!-- End Cloudflare Web Analytics -->
{{ end }}

defer 속성을 부여함으로써 HTML 파싱을 차단하지 않고 스크립트를 비동기적으로 불러와, DOM 구축 후에 실행시킬 수 있습니다. 이를 통해 초기 표시 속도(LCP: Largest Contentful Paint 나 FCP: First Contentful Paint)에 미치는 영향을 최소화할 수 있습니다.

8. 요약 및 베스트 프랙티스

Hugo를 이용한 정적 사이트 운영에 있어, Cloudflare Pages나 GitHub Pages와 같은 모던 호스팅 플랫폼을 채택하는 것은 가성비, 표시 속도, 보안의 모든 측면에서 압도적인 장점이 있습니다.

초고속 빌드: Hugo의 고속성을 살려 CI/CD 파이프라인(GitHub Actions)의 실행 시간을 최소화한다.
엣지 전송: Cloudflare의 엣지 네트워크를 이용하여 전 세계 사용자에게 밀리초 단위의 지연 시간으로 콘텐츠를 전달한다.
적절한 DNS 구성: CNAME Flattening을 활용하여 Zone Apex(독자 도메인)를 안전하고 빠르게 운영한다.
캐시 전략 최적화: _headers 를 사용하여 브라우저 캐시와 엣지 캐시를 리소스 종류에 따라 적절하게 분리한다.
가벼운 애널리틱스: 프라이버시를 배려하면서 퍼포먼스를 손상시키지 않는 Cloudflare Web Analytics 등을 도입한다.

이것들을 조합함으로써 월간 수백만 PV 클래스의 대규모 트래픽도 견뎌낼 수 있는, 확장 가능하고 견고한 블로그 시스템을 무료로 구축할 수 있습니다. 기술 블로그나 기업 사이트, 포트폴리오 사이트 개설을 검토하고 계신 분들은 꼭 이 Jamstack + Hugo + Cloudflare Pages 구성을 시도해 보시기 바랍니다.