정정지용
기술스택 목록
인프라

GitHub Pages

프로젝트 1개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

GitHub 저장소에 있는 정적 파일을 무료로 웹에 호스팅해주는 서비스

GitHub Pages는 GitHub 저장소에 담긴 HTML, CSS, JavaScript 같은 정적 파일을 별도의 서버 없이 웹에 그대로 배포해주는 정적 사이트 호스팅 서비스입니다. 개인 블로그, 프로젝트 소개 페이지, 문서 사이트처럼 서버 로직 없이 파일만 보여주면 되는 사이트를 빠르고 무료로 공개하기 위해 만들어졌습니다. 저장소에 코드를 푸시하면 GitHub가 자동으로 이를 빌드하거나 그대로 서빙해 지정된 주소로 접속할 수 있게 해줍니다.

이럴 때 사용합니다

  • 서버 없이 정적 파일만으로 이루어진 문서·소개 페이지를 무료로 공개하고 싶을 때
  • GitHub 저장소와 배포 과정을 별도 설정 없이 바로 연결하고 싶을 때
  • 오픈소스 프로젝트의 문서 사이트나 개인정보 처리방침 같은 고정 문서를 간단히 게시할 때
  • 별도 인프라 비용이나 서버 관리 부담 없이 정적 페이지를 유지하고 싶을 때

핵심 개념

repository
GitHub Pages는 특정 저장소(또는 저장소 안의 특정 브랜치·폴더)를 사이트의 소스로 지정해 그 내용을 그대로 배포합니다.
static site
서버에서 동적으로 데이터를 처리하지 않고 미리 만들어진 HTML/CSS/JS 파일만으로 구성된 사이트를 말하며, GitHub Pages는 이런 정적 사이트만 지원합니다.
branch deployment
보통 main 브랜치나 별도의 gh-pages 브랜치, 혹은 지정 폴더(docs 등)를 배포 대상으로 설정해 해당 내용이 변경될 때마다 사이트가 갱신됩니다.
custom domain
GitHub가 기본으로 제공하는 주소 대신 사용자가 소유한 도메인을 연결해 사이트를 서비스할 수 있습니다.
GitHub Actions build
정적 사이트 생성기(예: Jekyll, 또는 별도 빌드 도구)로 만든 결과물을 GitHub Actions 워크플로로 빌드한 뒤 Pages에 배포하는 방식도 지원합니다.

저장소 설정으로 Pages 배포 지정

main 브랜치에 푸시될 때마다 dist 폴더의 빌드 결과물을 GitHub Pages로 배포하는 워크플로 예시입니다.

YAML
# .github/workflows/deploy.yml
name: Deploy Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'
      - uses: actions/deploy-pages@v4

처음 쓸 때 흔한 함정

  • 빌드 산출물 경로를 잘못 지정하면 배포는 성공해도 빈 페이지나 404가 나타날 수 있습니다.
  • 비공개 저장소의 무료 플랜에서는 Pages 공개 범위나 사용 조건에 제약이 있을 수 있습니다.
  • 정적 파일만 서빙하므로 서버 측 로직이나 DB 연동이 필요한 기능은 별도 백엔드가 필요합니다.

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

JekyllMarkdownYAML