P7-7.1 배포 확인과 상태 점검¶

Section ID: P7-7.1 Version: v2026.07.22

Part 7의 마지막 프로젝트는 코드를 만들었다에서 끝나지 않습니다. 이 책 저장소처럼 정적 웹 문서를 배포하는 프로젝트도, 독자에게 실제로 보이기 시작하는 순간부터는 운영 질문이 생깁니다.

이 저장소에서는 평소 작업 브랜치가 dev이고, main에 push되면 GitHub Actions를 통해 GitHub Pages 배포가 실행됩니다. 따라서 원고를 수정했다, 로컬에서 빌드가 된다, 독자에게 실제로 공개되었다는 서로 다른 상태입니다.

목적은 GitHub Pages 사용법을 길게 설명하는 것이 아니라, 이 저장소를 기준으로 로컬 빌드 성공, 배포 트리거, 공개 페이지 확인을 분리해 읽는 기준을 잡는 데 있습니다.

배포 상태를 나눠 읽기¶

• 정적 문서 프로젝트를 배포한다는 것은 무엇을 뜻하는가?
• GitHub Pages는 어떤 종류의 배포 방식인가?
• 배포 후 무엇을 최소한 확인해야 하는가?

정적 문서 프로젝트의 빌드 -> 배포 -> 확인 최소 흐름에 집중합니다. 즉, 빌드 성공과 공개 상태 확인을 분리해 기록하는 기준을 먼저 닫습니다.

배포 프로젝트는 여기서 빌드, 배포 반영, 공개 페이지 확인을 나눠 보는 운영 기록으로 바뀝니다. 빌드 성공과 공개 상태 확인을 분리해 기록하는 기준을 세웁니다.

Part 7에서 배포(deployment)와 정적 배포(static deployment)를 같은 말처럼 읽게 되면 이 절과 개념사전으로 돌아와 구분을 다시 잡는 편이 좋습니다.

판단 기준¶

• 정적 사이트 배포를 빌드 -> 배포 -> 확인 흐름으로 설명할 수 있습니다.
• GitHub Pages가 정적 사이트 호스팅(static site hosting)이라는 점을 말할 수 있습니다.
• 배포 후 기본 상태 확인 체크리스트를 만들 수 있습니다.

왜 배포 프로젝트가 필요한가¶

개인 학습 프로젝트라도 배포를 거치면 다음 문제가 생깁니다.

• 로컬에서는 되는데 배포에서는 안 될 수 있다.
• 링크가 깨질 수 있다.
• 새 변경이 바로 반영되지 않을 수 있다.
• 빌드 성공과 공개 페이지 정상 동작은 같은 말이 아닐 수 있다.

이 저장소는 그 차이가 특히 분명합니다. AGENTS.md 기준으로 일반 작성은 dev에서 하고, main push는 곧 배포로 간주합니다. 또 .github/workflows/deploy.yml을 보면 main push 뒤에 Python 설치, pip install -r requirements.txt, mkdocs build --strict, Pages artifact 업로드, Pages 배포가 차례로 실행됩니다. 즉, 문서를 고친 뒤 로컬 폴더에 저장했다고 해서 바로 공개된 것이 아닙니다.

즉, 프로젝트는 단순 업로드가 아니라 정적 산출물을 공개 서비스로 전환하는 최소 운영 경험입니다.

배포 시작 기록에서 바로 확인해야 할 판단 기준을 표로 고정하면 다음과 같습니다.

예를 들어 GitHub Actions 화면이 초록색으로 끝난 것만 먼저 보면, 빠르게는 배포가 다 끝났고 독자도 최신 내용을 본다고 적고 싶어질 수 있습니다. 하지만 더 안전한 다음 판단은 그렇게 workflow 결과만으로 닫는 것이 아니라, 로컬 빌드가 어떤 커밋 기준으로 성공했는가, main 반영과 Pages deploy가 실제로 끝났는가, 공개 URL에서 최신 Version과 링크가 보이는가를 나눠 적는 것입니다. 그래야 CI 성공, 배포 완료, 공개 확인 완료를 같은 상태처럼 섞지 않게 됩니다.

flowchart TD
  A["문제 장면<br/>Actions가 초록색으로 끝남"]
  B["빠른 판단<br/>독자에게 최신 내용이 공개됐다"]
  C["빌드 기준 확인<br/>어느 커밋이 빌드됐는가"]
  D["배포 단계 확인<br/>Pages deploy가 끝났는가"]
  E["공개 URL 확인<br/>최신 Version과 링크가 보이는가"]
  F["더 안전한 판단<br/>CI 성공, 배포 완료, 공개 확인을 분리"]

  A --> B
  A --> C --> D --> E --> F

여기에 한 가지를 더 붙이면 운영 시작 절이 뒤의 실패 기록 절과 더 자연스럽게 이어집니다. 배포 목표 절에서도 단순 확인 항목만 적는 것이 아니라, 어떤 상태를 계속 볼 것인가, 무엇이 검토 대상인가, 어떤 경우 다음 점검을 다시 해야 하는가를 같이 남겨 두는 편이 좋습니다.

이 저장소의 실제 배포 경로¶

flowchart TD
  A["dev 브랜치에서 원고 수정"]
  B["로컬 빌드<br/>.venv/bin/python -m mkdocs build"]
  C["main 반영"]
  D["GitHub Actions build<br/>mkdocs build --strict"]
  E["Pages artifact 업로드"]
  F["GitHub Pages 배포"]
  G["공개 URL 확인<br/>https://devchan64.github.io/AiBook/"]

  A --> B --> C --> D --> E --> F --> G

이 도식은 배포를 파일 올리기 한 번이 아니라 작성, 로컬 확인, 배포 트리거, CI 빌드, 공개 확인으로 나누어 보게 해 줍니다. 특히 마지막 공개 URL 확인 단계가 있어야 Actions에서 초록색이 떴다와 독자가 최신 원고를 읽는다가 같은 말이 아니라는 점을 프로젝트 문서에 분명히 남길 수 있습니다.

프로젝트 기록으로 정리하면 순서는 다음과 같습니다.

이 레포에서 먼저 봐야 할 파일¶

배포 프로젝트를 읽을 때는 추상적인 웹 배포보다, 현재 저장소에서 배포가 어떻게 정의되어 있는지를 먼저 보는 편이 좋습니다.

이 네 파일을 보면 무엇을 고쳤는가, 무슨 명령이 돌 것인가, 어디에 공개될 것인가, 어떤 원고가 독자에게 보일 것인가가 한 번에 연결됩니다.

GitHub Pages에서 기억할 점¶

GitHub Docs는 GitHub Pages가 정적 파일을 배포하며, 필요하면 빌드 과정을 거쳐 공개 반영할 수 있다고 설명합니다. 또한 GitHub Actions를 배포 실행 경로로 사용할 수 있다고 안내합니다. 공개 저장소(public repository)에서는 Actions도 무료로 사용할 수 있습니다.

정적 문서 프로젝트 문맥에서는 아래 항목을 먼저 기억해 두면 됩니다.

• 배포 브랜치 반영 시 정적 사이트 배포가 실행될 수 있다.
• 산출물은 정적 파일이다.
• 배포 후 실제 공개 URL을 확인해야 한다.
• 변경 반영에는 시간이 걸릴 수 있다.

이 저장소에 그대로 옮기면 다음 세 줄이 핵심입니다.

• dev에서 고친 원고는 바로 공개되지 않는다.
• main 반영이 Pages 배포의 시작 신호다.
• 공개 URL에서 최신 Section 메타데이터와 링크를 직접 확인해야 한다.

실제로 무엇을 실행하고 무엇을 확인하는가¶

배포 직전이나 배포 직후에 실제로 손을 움직일 항목을 이 저장소 기준으로 적으면 다음과 같습니다.

1
2

git branch --show-current
.venv/bin/python -m mkdocs build

첫 줄은 지금 내가 배포 브랜치에서 작업 중인가, 아직 dev에서 검토 중인가를 확인하는 명령입니다. 둘째 줄은 원고와 nav, 링크 구조가 현재 로컬 기준으로는 빌드 가능한가를 확인하는 명령입니다.

이 두 줄만으로도 배포 프로젝트의 질문이 분명해집니다.

즉, 배포 프로젝트에서는 명령을 몇 개 안다보다 각 명령이 어느 층위의 상태를 확인하는가를 아는 편이 더 중요합니다.

AiBook 배포 확인표 예시¶

실제 원격 배포를 다시 실행하는 대신, 이 저장소를 배포한다고 가정했을 때 어떤 항목을 문서에 남겨야 하는지 적는 데 집중합니다.

배포 확인표를 표로만 읽고 끝내지 않으려면, 같은 형식을 실제 점검 기록 파일로도 다뤄 보는 편이 좋습니다. Python 예제에서는 배포 확인표 두 건을 p7-7-deployment-checks.csv · CSV 미리보기에 두고, 코드가 그 기록을 읽어 공개 확인까지 끝난 배포와 재확인이 필요한 배포를 구분합니다.

Python 예제¶

예제는 배포 확인표를 실제 기록 파일처럼 읽고, 같은 배포라도 어디에서 멈췄는지 실행 결과로 요약하는 것입니다. 예제에서는 단순히 성공/실패만 세지 않고, 배포별 점검 단계 수, 재확인 필요 항목, 최종 상태를 함께 남겨 실제 운영 메모처럼 읽히게 하겠습니다.

• 문제 상황: 같은 GitHub Pages 배포라도 공개 반영까지 끝난 경우와 아직 재확인이 필요한 경우를 구분한다.
• 입력: 배포 점검 기록 2건, 단계별 상태 8행
• 기대 출력: 배포별 요약, 재확인 필요 항목, 전체 검토 요약
• 확인할 개념:
• 배포 상태는 한 줄짜리 성공 메시지보다 단계별 기록으로 읽어야 한다
• workflow 성공과 공개 URL 최신 반영은 같은 상태가 아니다
• 재확인 필요 항목을 따로 남겨야 다음 운영 행동이 분명해진다

입력 파일¶

• 파일 경로: p7-7-deployment-checks.csv · CSV 미리보기
• 한 행의 의미: 배포 한 건의 점검 단계 하나
• 핵심 열: run_id, check_order, check_name, observed_value, recheck_required

즉, 이 파일은 배포 한 건 = 한 행이 아니라 배포 한 건 안의 점검 단계들 = 여러 행 구조입니다. Python 예제는 같은 run_id를 다시 묶어, 한 배포가 공개 확인까지 끝났는지 아니면 아직 재확인이 필요한지 계산합니다.

실행 기록 기준¶

배포 확인 기록은 성공 여부를 한 단어로 적지 않고, 빌드, workflow, 공개 URL, 최신 내용 반영을 단계별 상태로 나눕니다. 같은 배포 ID에는 여러 점검 단계가 묶이고, 재확인 필요 항목이 남은 배포는 별도 상태로 표시해야 합니다.

기록은 다음 기준으로 나눕니다.

1. run_id별로 어떤 점검 단계가 들어 있는지 확인합니다.
2. 각 단계의 observed_value가 실제 상태 설명인지, 단순 성공/실패 표시인지 구분합니다.
3. Python 예제를 실행해 공개 확인 완료와 재확인 필요 배포가 어떻게 갈리는지 봅니다.
4. 재확인 필요 항목을 보고, 다음에 다시 볼 위치를 한 줄로 적습니다.

 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

# 배포 점검 CSV를 run별로 묶어 공개 확인 완료와 재확인 필요 상태를 판정하는 예제입니다.
import csv
from collections import defaultdict
from pathlib import Path

data_path = Path("docs/assets/part-07/chapter-07/p7-7-deployment-checks.csv")
rows = list(csv.DictReader(data_path.open(encoding="utf-8")))
대표_run_ids = {"배포-001", "배포-002"}
rows = [row for row in rows if row["run_id"] in 대표_run_ids]

deployments = defaultdict(list)
for row in rows:
    deployments[row["run_id"]].append(row)

배포_요약 = []
for run_id, checks in deployments.items():
    checks.sort(key=lambda row: int(row["check_order"]))
    recheck_items = [
        f'{row["check_name"]}: {row["observed_value"]}'
        for row in checks
        if row["recheck_required"] == "예"
    ]
    final_status = "재확인 필요" if recheck_items else "공개 확인 완료"
    배포_요약.append({
        "배포 ID": run_id,
        "점검 단계 수": len(checks),
        "마지막 단계": checks[-1]["check_name"],
        "최종 상태": final_status,
        "재확인 필요 항목": recheck_items,
    })

검토_요약 = {
    "배포 수": len(배포_요약),
    "공개 확인 완료 수": sum(
        row["최종 상태"] == "공개 확인 완료" for row in 배포_요약
    ),
    "재확인 필요 수": sum(
        row["최종 상태"] == "재확인 필요" for row in 배포_요약
    ),
    "다시 볼 배포": [
        row["배포 ID"] for row in 배포_요약 if row["최종 상태"] == "재확인 필요"
    ],
}

print("읽은 파일 =", str(data_path))
print("배포별 요약 =")
for row in 배포_요약:
    print(row)
print("검토 요약 =", 검토_요약)

실행 결과 예시는 다음과 같습니다.

1
2
3
4
5

읽은 파일 = docs/assets/part-07/chapter-07/p7-7-deployment-checks.csv
배포별 요약 =
{'배포 ID': '배포-001', '점검 단계 수': 4, '마지막 단계': '공개 URL 확인', '최종 상태': '공개 확인 완료', '재확인 필요 항목': []}
{'배포 ID': '배포-002', '점검 단계 수': 4, '마지막 단계': '공개 URL 확인', '최종 상태': '재확인 필요', '재확인 필요 항목': ['Pages workflow: build job 완료 후 deploy 대기', '공개 URL 확인: 공개 주소에서 이전 Version이 아직 보임']}
검토 요약 = {'배포 수': 2, '공개 확인 완료 수': 1, '재확인 필요 수': 1, '다시 볼 배포': ['배포-002']}

결과를 어떻게 읽는가¶

이 출력에서 읽어야 할 핵심은 배포-001과 배포-002가 모두 로컬 빌드에는 성공했지만, 운영 상태는 같지 않다는 점입니다.

즉, 배포가 시작되었다와 독자가 최신 내용을 본다는 같은 말이 아닙니다.

• Pages workflow가 성공 또는 대기인지 기록하면 CI 단계와 공개 단계를 분리해 읽을 수 있습니다.
• 공개 URL 확인이 보류로 남으면 배포 실패라기보다 공개 반영 지연 또는 후속 확인 대기 상태로 해석할 수 있습니다.
• 따라서 배포 확인표에는 재확인 필요 항목을 남겨야 다음에 어디를 다시 볼지 분명해집니다.

이 결과는 다음 세 줄로 요약할 수 있습니다.

• 로컬 빌드 성공만으로는 공개 상태를 확정할 수 없다
• workflow 완료와 공개 URL 최신 반영 여부를 따로 기록해야 한다
• 재확인 필요 항목이 남은 배포는 운영 메모에서 별도 추적해야 한다

결과 해석 기준¶

이번 결과에서는 로컬 빌드 성공과 공개 확인 완료를 분리해서 봅니다. 배포 기록 중간에 재확인 항목이 하나라도 남아 있으면, 배포 자체가 실패했다고 단정하기보다 어느 단계가 아직 닫히지 않았는지 먼저 확인해야 합니다.

프로젝트 기록 예시¶

배포 기록은 세 상태를 섞지 않을수록 나중에 원인을 찾기 쉽습니다.

기록은 다음 형식으로 배포 확인 기록을 압축할 수 있습니다.

직접 바꿔 보며 확인할 것¶

점검 단계 하나만 바꿔도 최종 상태가 달라지는 구조를 일부러 보여 줍니다. 실행 뒤에는 다음 두 가지를 바꿔 보면 좋습니다.

1. 배포-002의 recheck_required 값을 모두 아니오로 바꿔 봅니다. 관찰할 점: 같은 배포도 재확인 항목이 사라지면 바로 공개 확인 완료로 닫히는가?

2. 배포-001에 공개 URL 확인 단계 하나를 더 추가하고 이전 Version 노출 같은 값을 넣어 봅니다. 관찰할 점: build와 deploy가 끝났더라도 공개 확인 단계 하나가 전체 상태를 다시 재확인 필요로 바꾸는가?

핵심 확인 기준은 배포 성공이 단일 상태가 아니라 점검 단계들의 묶음이라는 점입니다.

바로 쓰는 배포 확인 템플릿¶

배포 직후 문서에 바로 붙여 넣어 쓸 최소 확인 틀은 아래 정도로 시작할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

### 배포 확인표
- 빌드 상태:
- 배포 상태:
- 사이트 주소:
- 최신 내용 확인:
- 깨진 링크 확인:
- 메모:

### 모니터링 메모
- 독자에게 보이는 문제:
- 다음 확인 시점:

이 템플릿의 핵심은 배포했다에서 끝내지 않는 것입니다. 적어도 빌드는 성공했는가, main 반영이 실제로 배포를 일으켰는가, 공개 페이지는 열리는가, 최신 수정이 실제로 보이는가는 분리해 남겨야 합니다.

여기서 배포 확인표는 배포 직후 확인표 한 건이고, 모니터링 메모는 잠시 뒤 다시 볼 점을 남기는 짧은 운영 메모로 읽으면 됩니다.

가능하면 여기에 추가 검토 필요 또는 재확인 필요 같은 항목도 함께 두는 편이 좋습니다. 배포 직후에는 정상처럼 보여도, 공개 반영 지연이나 링크 오류가 조금 뒤에 드러날 수 있기 때문입니다.

즉, 배포 직후의 성공은 최종 결론이라기보다 현재 시점의 확인 신호에 가깝습니다. 바로 보이는 이상이 없더라도, 약간의 지연 뒤 다시 확인해야 드러나는 문제가 있을 수 있습니다.

이번 저장소에 맞춰 이 틀을 채우면 다음처럼 정리할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

### 배포 확인표
- 빌드 상태: `.venv/bin/python -m mkdocs build` 성공
- 배포 상태: `main` 반영 뒤 GitHub Actions Pages workflow 시작 확인
- 사이트 주소: https://devchan64.github.io/AiBook/
- 최신 내용 확인: 수정한 Section의 제목과 Version이 공개 페이지에 보임
- 깨진 링크 확인: 수정한 페이지의 앞뒤 링크와 목차 진입 링크 직접 확인
- 메모: 로컬 빌드 성공과 공개 반영 확인을 분리해 기록함

### 모니터링 메모
- 독자에게 보이는 문제: 없음
- 다음 확인 시점: 공개 반영 지연 가능성을 고려해 잠시 뒤 한 번 더 확인

나쁜 배포 확인 기록과 좋은 배포 확인 기록¶

배포 확인 기록도 자주 올렸다, 정상 같다 정도로 끝납니다. 아래처럼 대비해 보면 기준이 더 분명해집니다.

나쁜 기록은 배포 감상만 남고 실제 확인 항목이 없습니다. 좋은 기록은 빌드, 배포 상태, 공개 페이지, 최신 내용 반영, 깨진 링크가 각각 확인됐는지를 함께 남깁니다.

이 기록은 이후 실패 회고와 운영 점검의 입력 자료가 됩니다. 즉, 운영 시작 절은 단순 준비 설명이 아니라 무엇을 검토 대상으로 남길 것인가를 먼저 정하는 절입니다.

왜 정적 사이트도 운영 질문이 남는가¶

Google SRE 책은 monitoring을 실시간 수치 데이터를 수집하고 가공해 보여 주는 활동으로 설명합니다. 또한 alerting, dashboard, retrospective analysis 같은 목적을 함께 두며, 사용자 관점 시스템에서는 latency, traffic, errors, saturation 네 가지 golden signals를 우선 보라고 정리합니다.

정적 문서 사이트는 동적 서비스보다 단순하지만, 운영 질문은 여전히 남습니다.

• 페이지가 열리는가?
• 최근 배포가 반영되었는가?
• 오류 페이지가 보이지 않는가?
• 트래픽이 늘면 정적 파일 전달은 안정적인가?

이 저장소 수준에서 당장 붙잡아야 하는 것은 거대한 운영 대시보드가 아니라, 독자가 열어 본 첫 페이지가 최신인가, 핵심 링크가 끊기지 않는가, 방금 고친 절이 실제로 공개되었는가 같은 기본 신호입니다.

즉, 정적 문서 배포도 배포 후 확인 단계를 가져야 합니다.

Part 7 전체 흐름에서 정적 사이트도 서비스처럼 확인하고 기록해야 한다는 기준을 잡습니다.

체크리스트¶

이 다섯 칸이 비어 있으면 배포 자동화보다 먼저 브랜치 상태, 로컬 빌드, 배포 상태, 공개 페이지, 최신 내용 반영, 깨진 링크를 분리해 남겨야 합니다. - dev 작업과 main 배포를 구분해 적을 수 있는가? - 빌드 성공과 배포 성공을 분리해 적을 수 있는가? - 공개 URL과 수정한 Section의 최신 반영 여부를 확인했는가? - 링크 깨짐과 오류 페이지 여부를 점검했는가? - 정적 사이트도 운영 관점이 필요하다는 점을 설명할 수 있는가?

출처와 참고 자료¶

• GitHub Docs, What is GitHub Pages?, 확인 날짜: 2026-06-29. https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages
• GitHub Docs, Creating a GitHub Pages site, 확인 날짜: 2026-06-29. https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
• Google, Monitoring Distributed Systems, Site Reliability Engineering Book, 확인 날짜: 2026-06-29. https://sre.google/sre-book/monitoring-distributed-systems/