GitHub Actions를 사용한 GitHub Pages 설정

발행: 1개월 전 (2026년 1월 1일 오전 07:11 GMT+9)

13 분 소요

원문: Dev.to

Source: Dev.to

고수준 단계

Create GitHub Repository – GitHub에 새 저장소를 만듭니다.
Create Hello World Content – 제공할 기본 HTML 콘텐츠를 추가합니다.
Enable GitHub Pages – 저장소 설정에서 Pages를 구성합니다.
Set Up GitHub Actions – 워크플로를 사용해 배포를 자동화합니다.
Verify Deployment – 사이트가 라이브 상태인지 확인합니다.

필수 조건

GitHub 계정
Git이 로컬에 설치됨
HTML에 대한 기본 지식
텍스트 편집기 또는 IDE

사용 사례: 간단한 Hello World 사이트

우리는 “Hello World”를 표시하는 기본 정적 웹사이트를 만들고, 추가 콘텐츠를 통해 확장할 수 있습니다. 이 접근 방식은 모든 정적 HTML 사이트, 문서, 또는 간단한 웹 애플리케이션에 적용할 수 있습니다.

단계별 구현

단계 1: GitHub 저장소 만들기

GitHub에 접속하여 오른쪽 상단의 “+” 아이콘을 클릭합니다.
“New repository.”(새 저장소)를 선택합니다.

저장소 설정:

설정	값
저장소 이름	`github-pages-demo` (또는 원하는 이름)
설명	“A simple hello world site on GitHub Pages”
공개 여부	Public (무료 GitHub Pages에 필요)
README 초기화	✅ (checked)

“Create repository.”(저장소 만들기)를 클릭합니다.

핵심 포인트

저장소 이름은 사이트 URL의 일부가 됩니다: https://<username>.github.io/
공개 저장소는 무료 GitHub Pages 호스팅을 제공합니다.
비공개 저장소는 Pages를 사용하려면 GitHub Pro(이상) 구독이 필요합니다.

단계 2: 로컬에 저장소 복제하기

git clone https://github.com/your-username/github-pages-demo.git
cd github-pages-demo

your-username을 실제 GitHub 사용자 이름으로 바꿉니다.

단계 3: Hello World 콘텐츠 만들기

저장소 루트에 기본 index.html 파일을 생성합니다:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Hello World - GitHub Pages</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
    }
    .container {
      text-align: center;
      padding: 2rem;
    }
    h1 {
      font-size: 3rem;
      margin-bottom: 1rem;
    }
    p {
      font-size: 1.2rem;
      opacity: 0.9;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Hello World!</h1>
    <p>Welcome to my GitHub Pages site</p>
  </div>
</body>
</html>

이것이 생성하는 내용

“Hello World” 메시지가 포함

workflow file. If the workflow runs first, the github-pages environment won’t exist, causing the job to fail.

단계 5.1: Settings 이동

GitHub에서 리포지토리로 이동합니다.
상단 네비게이션 바에서 “Settings” 를 클릭합니다.
왼쪽 사이드바에서 “Pages.” 를 선택합니다.

단계 5.2: Source 구성

“Build and deployment” 아래에서 “Source.” 를 찾습니다.

“GitHub Actions.” 를 선택합니다.
선택은 자동으로 저장됩니다.

이 작업이 하는 일

리포지토리의 GitHub Pages를 활성화합니다.
배포를 위해 Pages가 GitHub Actions 워크플로를 사용하도록 설정합니다.
워크플로에 필요한 github-pages 환경을 생성합니다.

배포 확인

변경 사항(index.html 및 워크플로 파일 포함)을 main 브랜치에 커밋하고 푸시합니다:
```
git add .
git commit -m "Add site content and Pages workflow"
git push origin main
```
Actions 탭으로 이동하여 워크플로 실행을 확인합니다.
워크플로가 완료되면 Settings → Pages 로 이동하여 라이브 사이트 URL을 찾습니다(예: https://<username>.github.io/github-pages-demo).
브라우저에서 해당 URL을 열면 “Hello World!” 페이지가 표시됩니다.

요약

공개 저장소를 만들었습니다.
간단한 정적 사이트(index.html)를 추가했습니다.
GitHub Actions 워크플로를 설정하여 사이트를 자동으로 배포하도록 했습니다.
GitHub Actions를 소스로 하여 GitHub Pages를 활성화했습니다.
사이트가 정상적으로 라이브되는 것을 확인했습니다.

이제 main 브랜치에 푸시할 때마다 자동으로 업데이트되는 완전 자동화된 GitHub Pages 사이트가 준비되었습니다. 추가 페이지, 자산, 혹은 정적 사이트 생성기를 사용해 사이트를 확장하고 싶다면 워크플로를 그에 맞게 조정하면 됩니다.

6단계: 커밋 및 푸시

git add index.html .github/workflows/pages.yml
git commit -m "feat: add hello world page and GitHub Pages workflow"
git push origin main

Note: 이 튜토리얼에서는 간단히 main에 직접 푸시합니다. 실제 운영 환경에서는 다음과 같은 최선의 방법을 권장합니다:

브랜치를 생성합니다 (예: git checkout -b feature/add-pages-setup)
검토를 위한 풀 리퀘스트를 생성합니다
승인 후 병합합니다

핵심 포인트

main(또는 master) 브랜치는 일반적으로 GitHub Pages에 사용됩니다.
저장소 루트 또는 특정 브랜치/폴더에 있는 모든 파일을 제공할 수 있습니다.
GitHub Pages는 정적 파일만 제공합니다 (HTML, CSS, JavaScript, 이미지 등).
워크플로는 푸시 시 자동으로 트리거됩니다.

7단계: 배포 대기 및 사이트 접근

7.1 배포 대기

GitHub Actions가 워크플로 파일을 감지하고 자동으로 실행합니다.
GitHub가 사이트를 빌드하고 배포합니다(몇 분 정도 걸릴 수 있습니다).
녹색 체크 표시가 배포가 완료되었음을 나타냅니다.
Actions 탭에서 진행 상황을 모니터링합니다.

7.2 사이트 접근

Your site will be available at:

https://your-username.github.io/github-pages-demo

your-username와 github-pages-demo를 실제 값으로 교체하세요.

7.3 저장소 About 섹션에 웹사이트 추가 (선택 사항)

저장소 페이지에서 About 섹션 옆에 있는 톱니바퀴 아이콘(⚙️)을 클릭합니다.
Edit repository details 모달에서 Website 필드를 찾습니다.
GitHub Pages URL을 입력합니다(예: https://your-username.github.io/github-pages-demo).
**“Use your GitHub Pages website”**를 체크합니다 – URL이 자동으로 채워집니다.
Save changes를 클릭합니다.

이 작업이 하는 일

저장소 About 섹션에 사이트 URL을 표시합니다.
방문자를 위한 직접 링크를 제공합니다.
GitHub Pages 사이트의 검색 가능성을 높입니다.

Note: 향후 main 브랜치에 푸시하면 워크플로가 자동으로 트리거되어 업데이트가 배포됩니다.

전체 예시

저장소 구조

github-pages-demo/
├── .github/
│   └── workflows/
│       └── pages.yml
├── index.html
└── README.md

index.html – 3단계에 표시된 대로.
pages.yml – 4단계에 표시된 대로.

저장소 구조 요약

파일 / 폴더	목적
`.github/workflows/pages.yml`	GitHub Actions 배포 워크플로우
`index.html`	메인 페이지 내용
`README.md`	저장소 문서

Important Notes

GitHub Pages Limitations

Static content only – 서버‑사이드 처리(PHP, Python 등) 불가.
File size limits – 저장소 크기 1 GB, 파일당 100 MB 제한.
Bandwidth – 무료 계정은 월 100 GB까지.
Build time – 시간당 10번 빌드 제한.

Custom Domain Support

도메인 이름이 들어 있는 CNAME 파일을 추가합니다.
DNS 레코드를 GitHub을 가리키도록 설정합니다.
자세한 내용은 공식 GitHub Pages documentation 를 참고하세요.

AWS Route 53을 이용한 설정 방법은 Setting Up Custom Domain for GitHub Pages with Route53 를 참고하세요.

Branch and Folder Options

Source option	Description
Deploy from a branch	브랜치에서 파일을 직접 제공합니다.
GitHub Actions	워크플로를 사용해 빌드 및 배포(권장).

Folder option	Description
`/` (root)	저장소 루트에서 파일을 제공합니다.
`/docs`	`docs` 폴더에서 파일을 제공합니다.
custom	설정에서 지정한 임의의 폴더를 사용합니다.

Security Considerations

Public repositories – 콘텐츠가 공개적으로 접근 가능합니다.
Private repositories – Pages 사용을 위해 GitHub Pro 플랜이 필요합니다.
Secrets – API 키 등 민감한 데이터는 절대 커밋하지 마세요.
HTTPS – 모든 Pages 사이트에 자동으로 HTTPS가 적용됩니다.

문제 해결

사이트가 로드되지 않음

증상: 404 오류 또는 사이트가 로드되지 않음.

해결 단계

배포 상태 확인 – Repository → Actions 탭으로 이동합니다.
워크플로가 실행됐는지 확인 – 성공적으로 완료되었는지 확인합니다.
Pages 설정 확인 – 소스로 “GitHub Actions”가 선택되어 있는지 확인합니다.
몇 분 기다리기 – 초기 배포는 5‑10 분 정도 걸릴 수 있습니다.
브라우저 캐시 삭제 – 시크릿 모드나 다른 브라우저를 사용해 보세요.

유용한 명령어

# Verify workflow file exists
ls -la .github/workflows/pages.yml

# View its contents
cat .github/workflows/pages.yml

워크플로 실패

증상: GitHub Actions 워크플로 오류.

해결 체크리스트

Actions 탭 로그에서 오류 메시지를 검토합니다.
Pages 권한이 활성화되어 있는지 확인합니다 (pages: write, id-token: write).
아티팩트 경로가 콘텐츠 위치와 일치하는지 확인합니다 ('.'는 루트, 또는 올바른 폴더).
워크플로가 올바른 브랜치에서 트리거되는지 확인합니다.
YAML 구문을 검증합니다 (필요하면 온라인 린터 사용).

일반적인 오류

권한 누락: pages: write와 id-token: write를 추가합니다.
잘못된 아티팩트 경로: '.' 또는 적절한 폴더로 조정합니다.
브랜치 이름 불일치: on: 트리거가 브랜치와 일치하는지 확인합니다.

맞춤 도메인 문제

증상: 맞춤 도메인이 작동하지 않음.

해결 단계

CNAME 파일 확인 – 도메인 이름만 포함해야 하며(여분의 공백 없음) 확인합니다.
DNS 레코드 확인 – A/CNAME 레코드가 GitHub 서버를 가리키는지 확인합니다.
전파 허용 – DNS 변경은 최대 48 시간이 걸릴 수 있습니다.
GitHub 설정 확인 – 도메인이 Pages 설정에 추가되어 있어야 합니다.

검증

사이트 URL을 방문합니다.
“Hello World!” 내용이 올바르게 표시되는지 확인합니다.
Actions 탭에서 성공적인 실행을 확인합니다.

GitHub Actions를 사용한 GitHub Pages 설정

고수준 단계

필수 조건

사용 사례: 간단한 Hello World 사이트

단계별 구현

단계 1: GitHub 저장소 만들기

단계 2: 로컬에 저장소 복제하기

단계 3: Hello World 콘텐츠 만들기

단계 5.1: Settings 이동

단계 5.2: Source 구성

배포 확인

요약

6단계: 커밋 및 푸시

핵심 포인트

7단계: 배포 대기 및 사이트 접근

7.1 배포 대기

7.2 사이트 접근

7.3 저장소 About 섹션에 웹사이트 추가 (선택 사항)

전체 예시

저장소 구조

저장소 구조 요약

Important Notes

GitHub Pages Limitations

Custom Domain Support

Branch and Folder Options

Security Considerations

문제 해결

사이트가 로드되지 않음

워크플로 실패

맞춤 도메인 문제

검증

관련 글

RGB LED 사이드퀘스트 💡

Zapier vs. Custom Code: ‘Glue’ 툴을 언제 사용해야 할까

Mendex: 내가 만드는 이유

왜 Apache Ozone이 빅 데이터에 선호되는 Object Store인가

고수준 단계

필수 조건

사용 사례: 간단한 Hello World 사이트

단계별 구현

단계 1: GitHub 저장소 만들기

단계 2: 로컬에 저장소 복제하기

단계 3: Hello World 콘텐츠 만들기

단계 5.1: Settings 이동

단계 5.2: Source 구성

배포 확인

요약

6단계: 커밋 및 푸시

핵심 포인트

7단계: 배포 대기 및 사이트 접근

7.1 배포 대기

7.2 사이트 접근

7.3 저장소 About 섹션에 웹사이트 추가 (선택 사항)

전체 예시

저장소 구조

저장소 구조 요약

Important Notes

GitHub Pages Limitations

Custom Domain Support

Branch and Folder Options

Security Considerations

문제 해결

사이트가 로드되지 않음

워크플로 실패

맞춤 도메인 문제

검증

관련 글

RGB LED 사이드퀘스트 💡

Zapier vs. Custom Code: ‘Glue’ 툴을 언제 사용해야 할까

Mendex: 내가 만드는 이유

왜 Apache Ozone이 빅 데이터에 선호되는 Object Store인가

7.1 배포 대기

7.2 사이트 접근

7.3 저장소 About 섹션에 웹사이트 추가 (선택 사항)