문서도 GitHub에서 관리하기: PR 리뷰와 GitHub Actions로 자동 검사

명세서나 절차서를 Word나 Excel 파일로 공유 폴더에 두고 계시지는 않나요? '최신 버전이 무엇인지?', '누가 어디를 변경했는지?' 알 수 없게 되는 것은 흔한 고민입니다.

문서도 코드와 마찬가지로 GitHub에서 관리할 수 있습니다. 변경 사항은 PR(풀 리퀘스트)로 리뷰하고, 서식 오류는 GitHub Actions로 자동 검사하는 방식입니다. 이 글에서는 그 시작 방법을 소개합니다.

예시로, 이 시리즈의 아티클을 관리하는 레포지토리를 사용하겠습니다. 본문에서 소개하는 시스템은 실제로 이 레포지토리에서 작동하고 있습니다. 명세서든 사내 Wiki든, Markdown으로 작성할 수 있다면 같은 방식으로 사용할 수 있습니다.

왜 문서를 GitHub에서 관리해야 하는가

문서를 코드와 동일한 방식으로 관리하는 개념을 'Docs as Code'라고 부릅니다. 주요 장점은 다음 4가지입니다.

• 이력이 남는다. 언제, 누가, 무엇을, 왜 변경했는지 모두 기록됩니다. '이전 버전으로 되돌리고 싶다'도 즉시 가능합니다. - 차이점을 볼 수 있다. 변경된 부분만 행 단위로 확인할 수 있습니다. Word나 Excel에서는 어려운 점입니다. - 리뷰할 수 있다. 변경 사항을 PR에 올리면, 공개하거나 반영하기 전에 다른 사람이 검토할 수 있습니다. - 자동으로 검사할 수 있다. 서식 오류나 필수 항목 누락 등을 사람 대신 기계가 찾아줍니다.

그리고 AI와도 궁합이 뛰어납니다. Markdown 파일이 레포지토리에 있으면 에이전트형 AI가 그대로 읽을 수 있습니다. 명세서를 Markdown으로 변환하여 레포지토리에 두는 것은, AI에게 좋은 input을 제공하는 하네스(harness)를 구축하는 작업이기도 합니다 (하네스에 대해서는 다른 글에서 작성했습니다).

전체적인 흐름

이 글에서 만들게 될 과정은 다음과 같습니다.

• 작업용 브랜치를 생성하고 문서를 작성한다.
• PR을 만든다.
• GitHub Actions가 Markdown의 서식과 front matter를 자동으로 검사한다.
• 사람(또는 AI)이 PR을 리뷰한다.
• 검사와 리뷰가 통과되면 main에 병합(merge)한다.

main에 들어간 내용만이 '공식적인 버전'이 됩니다. Zenn의 경우, main에 병합되는 시점에 아티클이 반영됩니다.

단계 1: 폴더 구조 결정하기

먼저 어디에 무엇을 둘지 정합니다. Zenn 레포지토리라면 다음과 같은 구성입니다.

zenn-articles/
articles/ ← 아티클 (1개 아티클 = 1 파일)
scripts/
...

명세서의 경우, docs/ 아래에 기능별 폴더를 나누는 것이 일반적입니다. 중요한 것은 보관 위치 규칙을 README에 작성하는 것입니다. 사람도 AI도 README만 보면 헤매지 않습니다.

단계 2: PR로 리뷰 흐름 만들기

브랜치를 분기하고 PR 만들기

main에 직접 push하지 않고, 작업별로 브랜치를 나눕니다.

git switch -c add-github-docs-article
# 아티클 작성
git add articles/github-docs-pr-review-actions-lint.md
...

push하면 GitHub 화면에 'Compare & pull request' 버튼이 나타납니다. 여기서 PR을 만들 수 있습니다.

PR 템플릿 준비하기

.github/pull_request_template.md 파일을 두면, PR을 만들 때마다 그 내용이 본문에 포함됩니다. 리뷰에서 매번 확인하고 싶은 것을 체크리스트로 만들어 두세요.

## 변경 내용
<!-- 무엇을 작성했거나 고쳤는지 1~2줄로 -->
## 체크리스트
...

main을 보호하는 규칙 설정하기

레포지토리의 Settings에 있는 Rules(규칙 세트)에서 main 브랜치에 대한 규칙을 설정할 수 있습니다. 추천하는 것은 다음 2가지입니다.

PR을 통과해야 병합할 수 있도록 하기
GitHub Actions 검사가 통과해야 병합할 수 있도록 하기

혼자 운영하는 레포지토리라면, 리뷰 승인 필수까지는 설정하지 않아도 괜찮습니다. 검사만 통과하는 것을 필수로 하면, 실수가 main에 들어가는 것을 막을 수 있습니다. 화면의 항목명은 바뀔 수 있으므로 자세한 내용은 GitHub 공식 문서를 확인해 주세요.

lint(리인트)는 서식 오류나 작성 방식의 불일치를 기계적으로 찾아내는 시스템입니다. Markdown에는 markdownlint라는 도구가 자주 사용됩니다.

먼저 로컬에서 시도해 보기

GitHub Actions에 바로 넣기 전에, 로컬에서 한 번 실행해 봅시다. Node.js가 설치되어 있다면, 별도의 설치 없이 테스트할 수 있습니다.

npx markdownlint-cli2 "articles/*.md"

이 시리즈의 아티클에 실제로 적용해 본 결과, 다음과 같은 지적이 나왔습니다.

규칙 설정하기

리포지토리 루트 디렉터리에 .markdownlint-cli2.jsonc 파일을 만듭니다.

{
"config": {
"default": true,
...

"default": true로 모든 규칙을 활성화한 후, 맞지 않는 것만 false로 설정합니다. 제외한 규칙에는 왜 제외했는지 주석으로 남겨두는 것이 좋습니다. 나중에 보는 사람(그리고 AI)이 혼란스러워하지 않도록 말입니다.

단계 4: front matter 자동 검사하기

Zenn 아티클의 맨 앞에는 front matter라는 설정 영역이 있습니다.

---
title: "아티클 제목"
emoji: "📚"
...

여기를 잘못 작성하면, 아티클이 제대로 반영되지 않습니다. Zenn 공식 가이드에서는 주로 다음과 같은 규칙을 정하고 있습니다.

• emoji는 이모지 1개
• type은 tech (기술 아티클) 또는 idea (아이디어 아티클)
• topics는 최대 5개까지
• published는 true (공개) 또는 false (임시 저장) - 파일명(slug)은 a-z0-9, 하이픈(-), 언더스코어()의 12~50자

이를 검사하는 스크립트를 scripts/check-frontmatter.mjs에 넣습니다. 추가 패키지 없이 Node.js만으로 작동합니다.

// scripts/check-frontmatter.mjs
// Zenn의 아티클(articles/*.md)의 front matter를 검사하는 스크립트
import { readdirSync, readFileSync } from "node:fs";
...

로컬에서 node scripts/check-frontmatter.mjs를 실행하면, 문제가 있을 경우 다음과 같이 알려줍니다.

articles/Bad_Slug.md: 파일명은 a-z0-9, 하이픈(-), 언더스코어(\)의 12~50자여야 합니다
articles/Bad_Slug.md: emoji는 이모지 1개여야 합니다
articles/Bad_Slug.md: topics는 1~5개여야 합니다
...

에러 메시지는 일본어로, 수정 방법을 알 수 있도록 작성하는 것이 핵심입니다. 에러를 본 사람도, AI도 즉시 고칠 수 있게 말이죠.

단계 5: GitHub Actions 설정 작성하기

마지막으로, PR이 발생할 때마다 두 가지 검사가 자동으로 실행되도록 합니다. .github/workflows/check-articles.yml 파일을 만듭니다.

name: Check articles
on:
pull_request:
...

위에서부터 순서대로, 다음과 같은 의미입니다.

• on: 아티클이나 설정 파일이 변경된 PR일 때만 작동 -
• checkout: 리포지토리의 파일을 가져옴 -
• setup-node: Node.js를 준비함 -
• markdownlint-cli2-action: articles/의 Markdown을 lint 함 -
• run: 방금 만든 front matter 검사를 실행함

이것을 push하고 PR을 만들면, PR 화면 하단에 검사 결과가 표시됩니다. 실패했다면, 'Details'에서 무엇이 걸렸는지 확인할 수 있습니다.

참고로, @v7나 @v24

이것은 액션의 버전입니다. 각 액션은 정기적으로 업데이트되므로, 사용하기 전에 각각의 GitHub Releases에서 최신 버전을 확인해 주세요.

AI에게도 리뷰 맡기기

검사가 기계로 가능한 부분은 자동화하면, 사람의 리뷰는 내용에 집중할 수 있습니다. 게다가 PR 리뷰를 AI가 도와주도록 할 수도 있습니다. GitHub Copilot의 코드 리뷰 기능이나 Claude Code의 GitHub 연동 등, PR에 AI의 리뷰 코멘트를 달 수 있습니다. 설정 방법은 툴마다 다르므로, 각 공식 문서를 확인해 주세요.

AI에게 문서 리뷰를 부탁할 때는 관점을 명확하게 적으면 정확도가 높아집니다.

이 PR 아티클을 AI에게 자세히 모르는 초보 독자의 시각으로 리뷰해 주세요. 이해하기 어려운 용어, 설명이 빠진 부분, 사실 확인이 필요한 기술 등을 중요도 순서대로 언급해 주세요.

역할 분담은 이렇게 생각하면 이해하기 쉽습니다.

흔한 실수

처음부터 규칙을 너무 엄격하게 잡기

markdownlint의 규칙을 전부 활성화하면, 기존 문서에서 대량의 에러가 발생합니다. 처음에는 맞지 않는 규칙을 제외하고, 익숙해진 후에 조금씩 늘려가세요.

에러가 나올 때마다 규칙을 제외하기

반대로, 귀찮으니까라며 무엇이든 제외하면, 검사의 의미가 없어집니다. 제외하는 것은 '팀의 작성 방식으로서 의도한 것'에만 하세요. 제외한 이유는 설정 파일에 코멘트로 남깁니다.

main에 직접 push할 수 있게 두기

검사를 만들어도, main에 직접 push되면 통과입니다. 규칙 세트에서 PR과 검사를 필수로 지정해 주세요.

액션의 버전을 오래 방치하기

GitHub Actions의 실행 환경은 조금씩 업데이트되고 있습니다. 오래된 버전의 액션이 어느 날 갑자기 작동하지 않게 되는 경우도 있습니다. 가끔 Releases를 확인하거나, GitHub의 Dependabot을 사용해 버전 업데이트 PR을 자동으로 만들게 하면 안심할 수 있습니다.

요약

문서를 GitHub에서 관리하면, 이력, 차이점, 리뷰, 자동 검사가 모두 얻어집니다.

• Markdown으로 리포지토리에 배치하기
• PR로 리뷰하기
• 형식과 front matter는 GitHub Actions로 검사하기
• 내용은 AI와 사람이 리뷰하기

기계가 할 수 있는 것은 기계에 맡기고, 사람은 '무엇을 쓸 것인가'에 집중합니다. AI가 작성한 글이 늘어날 앞으로야말로, 이러한 시스템이 효과를 발휘할 것입니다.