6강. Docusaurus 사이트를 GitHub Pages에 처음 배포하기

?1. 이번 강의에서 해결할 문제

첫 배포에서 저장소 이름과 baseUrl이 다르거나 Pages 원본이 잘못되면 CSS와 내부 링크가 깨집니다. 기존 설정을 덮어쓰기 전에 값과 workflow를 읽습니다.

✓2. 학습 목표

✓이 강의를 마치면

• Docusaurus url, baseUrl, 조직·프로젝트 설정을 검증합니다.
• Pages build artifact와 deploy job의 관계를 설명합니다.
• GitHub 웹에서 Actions 배포 원본과 실행 결과를 확인합니다.

◇3. 핵심 개념

Docusaurus는 npm run build로 build 디렉터리만 만들고 호스팅은 외부 서비스 책임입니다. 일반적인 Pages workflow는 main push에서 source checkout→Node 설정→npm ci→build→Pages artifact 업로드→deploy 순서로 실행됩니다. 기본 GitHub 프로젝트 URL을 사용한다면 baseUrl에 저장소 이름이 포함됩니다.

정확히는 Pages workflow가 구성된 저장소라면 위 순서로 동작합니다. 파일이 없거나 비어 있거나 다른 호스팅 공급자를 사용한다면 GitHub Pages 배포가 구성된 상태가 아닙니다. 기존 공급자 설정을 Pages 예제로 덮어쓰지 말고 현재 운영 방식을 먼저 확인합니다.

URL 형태별 설정

공개 형태	예	일반적인 url	일반적인 baseUrl
사용자/조직 사이트	https://owner.github.io/	https://owner.github.io	/
프로젝트 사이트	https://owner.github.io/repository/	https://owner.github.io	/repository/
루트 커스텀 도메인	https://example.com/	https://example.com	/

따라서 "프로젝트 저장소니까 항상 /repository/"라고 정하면 커스텀 도메인에서 경로가 중복될 수 있습니다. 실제 공개 URL을 먼저 쓰고, 그 URL에서 사이트가 제공되는 하위 경로를 baseUrl로 정합니다.

build와 deploy 책임

source checkout
  → lockfile 설치
  → Docusaurus build
  → build 폴더를 Pages artifact로 업로드
  → deploy job이 artifact 게시
  → page_url에서 사용자 검증

artifact는 두 job 사이에서 전달하는 정적 파일 묶음입니다. deploy job이 소스를 다시 빌드하지 않으므로 build에서 검증한 바로 그 산출물이 게시됩니다.

Docusaurus 공식 배포 문서의 URL 설정과 GitHub Pages 절차를 기준으로 합니다.

✎4. 단계별 실습

1. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 파일을 새 예제로 교체하지 않습니다.

대상: 현재 설정과 workflow를 읽기 전용 검토

PowerShell

$configPath = "docusaurus.config.js"
$workflowPath = ".github\workflows\deploy-pages.yml"

Select-String -Path $configPath -Pattern "url:|baseUrl:|projectName:|organizationName:|trailingSlash:"

if (-not (Test-Path -LiteralPath $workflowPath)) {
  throw "Pages workflow가 없습니다. 현재 호스팅 공급자부터 확인하세요."
}

$workflowText = Get-Content -Raw -LiteralPath $workflowPath
if ([string]::IsNullOrWhiteSpace($workflowText)) {
  throw "Pages workflow가 비어 있습니다. 배포가 구성된 것으로 판단하지 마세요."
}

Get-Content -LiteralPath $workflowPath
npm.cmd run build

예상 결과: URL 설정과 build/deploy job이 표시되고 로컬 빌드가 성공합니다.

위 검사는 읽기 전용이며 조건을 만족하지 않으면 배포 실행 전에 중지합니다. workflow를 찾지 못했다고 즉석에서 YAML을 만들거나 현재 Cloudflare 같은 다른 공급자 설정을 삭제하지 않습니다. Pages를 실제로 선택한 별도 실습 저장소라면 공식 문서를 기준으로 최소 권한과 trigger를 검토합니다.

2. GitHub 웹 화면

실행 위치: 저장소 Settings → Pages

실행 전 확인: workflow와 main 브랜치가 원격에 있는지 확인합니다.

대상: Build and deployment source

GitHub 웹 화면

1. Source를 GitHub Actions로 선택
2. Actions 탭에서 Pages workflow 열기
3. build와 deploy job 성공 확인
4. deployment의 page_url 열기

예상 결과: 두 job이 성공하고 프로젝트 Pages URL에서 사이트가 열립니다.

성공 판정에 필요한 구체 결과

• build job과 deploy job이 모두 성공해야 합니다.
• deployment의 page_url이 config에서 예상한 주소와 일치해야 합니다.
• page_url에서 HTML뿐 아니라 CSS·JS·이미지 요청도 성공해야 합니다.
• 직접 경로 새로 고침과 없는 경로의 404가 의도대로 동작해야 합니다.
• 배포된 화면이 어느 commit SHA에서 생성됐는지 기록해야 합니다.

job이 초록색이어도 잘못된 URL을 게시했거나 에셋 경로가 깨졌다면 완료가 아닙니다.

→5. 배포·운영 흐름이 동작하는 이유

build job은 소스와 의존성으로 정적 artifact를 만들고 deploy job은 Pages 전용 권한으로 그 artifact를 게시합니다. 분리된 job과 최소 권한은 빌드 실패가 게시 단계로 넘어가는 것을 막습니다.

!6. 자주 하는 실수와 안전한 해결법

!자주 하는 실수

• 실수: 기존 workflow를 복사 예제로 덮어씀 안전한 해결: 현재 action 버전과 권한을 읽고 필요한 변경만 PR로 제안합니다.
• 실수: 공개 URL을 확인하지 않고 baseUrl 결정 안전한 해결: GitHub 프로젝트 URL은 /REPOSITORY/, 루트 커스텀 도메인은 /인지 실제 주소 기준으로 확인합니다.
• 실수: 배포 토큰을 YAML에 직접 작성 안전한 해결: 공식 Pages action의 GITHUB_TOKEN 권한을 사용하고 실제 토큰을 커밋하지 않습니다.

✎7. 직접 실습

✎직접 실습

실습 목표

기존 배포 설정을 덮어쓰지 않고 Pages 적용 여부, URL 설정, workflow, 실제 page_url을 순서대로 검증합니다.

시작 전 상태

현재 호스팅 공급자, 배포 브랜치, config 경로, workflow 존재·내용 여부를 읽기 전용으로 기록합니다. Pages가 아닌 운영 사이트에는 이 실습을 강제로 적용하지 않습니다.

1단계: 따라 하기

안전 검사 스크립트로 url/baseUrl과 workflow를 읽습니다. 파일이 없거나 비어 있으면 그 상태를 결과로 기록하고 중지합니다. 구성되어 있다면 build·artifact·deploy 단계를 표시합니다.

2단계: 설정을 비교하기

프로젝트 기본 URL과 루트 커스텀 도메인 두 경우의 예상 url, baseUrl, 최종 강의 URL을 표로 작성합니다. 실제 운영 주소에 맞는 한 행만 선택합니다.

3단계: 직접 적용

Pages를 쓰는 실습 저장소에서 로컬 build, Actions 두 job, page_url, CSS·이미지·직접 경로 새로 고침을 검증합니다. 실패하면 배포 job 재실행 전에 최초 실패 단계와 SHA를 기록합니다.

4단계: 스스로 확인

• 기존 workflow나 공급자 설정을 예제로 덮어쓰지 않았나요?
• artifact를 만든 SHA와 실제 배포 SHA가 일치하나요?
• page_url의 base 경로에서 정적 에셋도 성공하나요?

막혔을 때

• workflow 파일 없음/비어 있음: Pages가 구성됐다고 가정하지 말고 현재 공급자와 저장소 이력을 확인합니다.
• Actions trigger 오류: YAML의 on과 들여쓰기를 공식 예제와 비교하되 빈 trigger를 남기지 않습니다.
• 사이트는 열리지만 CSS가 없음: 공개 URL과 baseUrl, artifact 내부 경로를 비교합니다.
• deploy job 권한 실패: 토큰을 YAML에 쓰지 말고 Pages 공식 권한과 저장소 Settings를 확인합니다.

실습 기록에는 변경 SHA, 실행 위치, 확인 대상, 예상 결과와 실제 결과를 남기고 실제 토큰·비밀번호·SSH 개인 키·.env 내용은 포함하지 않습니다.

?8. 이해 점검 질문 3개

?이해 점검

1. Docusaurus의 책임은 build 이후 어디까지인가요?
2. Pages artifact는 두 job 사이에서 어떤 역할을 하나요?
3. 같은 저장소를 owner.github.io/repository/와 루트 커스텀 도메인에서 각각 제공할 때 baseUrl은 어떻게 달라지나요?

■9. 핵심 요약

■핵심 요약

첫 Pages 배포는 정확한 URL 설정, 로컬 build, Actions source 선택, build·deploy job과 page_url 확인으로 완성됩니다. 기존 설정을 읽고 최소 변경만 적용합니다.

§다음 강의 연결

첫 게시가 끝났다면 7강. 배포 후 검증에서 page_url의 핵심 경로·에셋·모바일·콘솔을 실제 사용자 조건으로 검사합니다.