배포 방식

배포 방법 선택

GitHub Pages로 배포하기 위해 두 가지 방법 중 하나를 선택할 수 있습니다: gh-pages 브랜치를 사용하는 방법과 docs 디렉토리를 사용하는 방법입니다. 배포 방법을 선택할 때 고려할 사항을 요약하면 다음과 같습니다.

• 독립된 브랜치 관리
  • gh-pages 브랜치를 사용하면 빌드 결과물과 소스 코드를 분리하여 관리할 수 있습니다.
  • 이는 대규모 프로젝트나 복잡한 배포 파이프라인을 사용하는 경우 유용합니다.
• 간편한 설정
  • docs 폴더를 사용하는 방법은 설정이 간단하며, 작은 규모의 프로젝트나 개인 블로그와 같은 단순한 사이트에 적합합니다.
  • 이 방법은 별도의 브랜치를 관리할 필요가 없습니다.

gh-pages 브랜치 방식

gh-pages 브랜치의 의미

gh-pages 브랜치는 GitHub Pages에서 제공하는 기능 중 하나로, 브랜치를 사용하여 웹사이트를 호스팅할 수 있습니다. 이 브랜치를 사용하면 Hugo나 다른 정적 사이트 생성기로 생성된 사이트를 별도의 브랜치로 관리할 수 있습니다.

주요 특징

• 독립된 브랜치
  • gh-pages 브랜치는 사이트의 빌드 결과물만을 포함하는 독립된 브랜치입니다.
  • 주 브랜치(master 또는 main)와 분리되어 있어, 원본 소스코드와 빌드 결과물을 명확히 구분할 수 있습니다.
• 자동 배포
  • 이 브랜치에 푸시된 내용은 GitHub Pages에서 자동으로 인식하여 배포합니다.
  • 별도의 설정 없이 웹사이트가 호스팅됩니다.
• 정리된 파일 구조
  • 주 브랜치에는 소스 코드만 남기고, 빌드된 파일은 gh-pages 브랜치로 푸시하여 파일 구조를 깔끔하게 유지할 수 있습니다.

gh-pages 브랜치 사용

Git 초기화

• Git을 초기화하고, 원격 저장소를 설정합니다.

# 새로운 Git 저장소 초기화
git init
# 원격 저장소 추가
git remote add origin https://github.com/USER_NAME/USER_NAME.github.io.git  

• 필요한 파일들을 커밋하고 원격 저장소에 푸시합니다.

git add .
git commit -m "Initial commit"
git push -u origin master

gh-pages 브랜치 초기화

• 최초 1회만 실행합니다.
• gh-pages 브랜치를 생성합니다.
• 이 단계에서는 public 디렉토리를 비워두는게 좋습니다.

# gh-pages 브랜치 생성
git checkout --orphan gh-pages
# `.git` 폴더를 제외한 모든 파일 제거
Get-ChildItem -Exclude ".git" | Remove-Item -Recurse -Force
# 빈 커밋 생성
git commit --allow-empty -m "Initialize new gh-pages branch"
git push origin gh-pages 
git checkout master

GitHub Actions를 사용한 자동 배포

자동으로 Hugo 사이트를 빌드하고 GitHub Pages로 배포하려면 GitHub Actions를 사용할 수 있습니다.

• .github/workflows 디렉토리를 생성하고, deploy.yml 파일을 추가합니다.
• deploy.yml 파일에 다음 내용을 추가합니다.

name: Deploy Hugo site to GitHub Pages
on:
  push:
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2
      with:
        hugo-version: '0.127.0'  # 로컬에서 사용하는 Hugo 버전으로 설정
    - name: Build
      run: hugo --minify --ignoreCache
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public
        publish_branch: gh-pages

• master 브랜치에 커밋이 푸시될 때마다 Hugo 사이트를 빌드하고, 빌드된 결과물을 gh-pages 브랜치에 푸시하는 역할을 수행합니다.
  • 저장소의 코드를 체크아웃합니다.
  • 최신 버전의 Hugo를 설정합니다.
  • Hugo를 사용하여 사이트를 빌드하고 결과물을 public 디렉토리에 저장합니다.
  • public 디렉토리의 내용을 gh-pages 브랜치에 푸시하여 GitHub Pages에 배포합니다.
• 이 파일을 커밋하고 푸시합니다.

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow for deploying to GitHub Pages"
git push origin master

GitHub Pages 설정

1. GitHub 저장소의 설정(Settings)에서 GitHub Pages 섹션으로 이동하여, Source를 gh-pages 브랜치로 설정합니다.
   • 저장소의 Settings로 이동합니다.
   • 왼쪽 사이드바에서 Pages를 클릭합니다.
   • Source 드롭다운 메뉴에서 Deply from a branch 를 선택합니다.
   • Branch 메뉴에서 gh-pages를 선택합니다.
   • Save 버튼을 클릭하여 설정을 저장합니다.

docs 디렉토리 방식

docs 폴더의 의미와 커밋의 의미

docs 폴더를 사용하여 GitHub Pages로 배포하는 방법은 GitHub 저장소의 루트 디렉토리에 빌드된 파일을 포함하지 않으면서도 GitHub Pages 기능을 활용할 수 있는 방법입니다.

주요 특징

• 루트 디렉토리 외부에 배포
  • docs 폴더는 저장소의 루트 디렉토리에 위치하지만, GitHub Pages는 이 폴더 내의 파일을 배포합니다.
  • 이는 주 브랜치(master 또는 main) 내에서 빌드 결과물을 포함할 수 있는 방법입니다.
• 간단한 설정
  • config.toml 파일에서 publishDir 설정을 통해 Hugo가 빌드된 파일을 docs 폴더에 저장하도록 할 수 있습니다.
  • 이를 통해 GitHub Pages 설정에서 docs 폴더를 지정하면 별도의 브랜치를 사용하지 않고도 사이트를 배포할 수 있습니다.
• 커밋의 의미
  • docs 폴더에 빌드된 파일을 커밋하고 푸시하면, GitHub Pages는 이 폴더의 내용을 인식하여 웹사이트를 업데이트합니다.
  • 이는 gh-pages 브랜치를 사용하는 것과 동일한 효과를 가집니다.

docs 디렉토리 사용

• Hugo 사이트를 docs 디렉토리에 빌드하도록 설정합니다.
• config.toml 파일을 수정하여 다음과 같이 설정합니다.

publishDir = "docs"

• Hugo 사이트를 다시 빌드합니다.

hugo

• docs 디렉토리를 커밋하고 푸시합니다.

git add docs
git commit -m "Deploy to GitHub Pages using docs directory"
git push origin master

• GitHub 저장소 설정에서 GitHub Pages 설정을 docs 디렉토리로 지정합니다.

GitHub Actions를 사용한 자동 배포

자동으로 Hugo 사이트를 빌드하고 GitHub Pages로 배포하려면 GitHub Actions를 사용할 수 있습니다.

• .github/workflows 디렉토리를 생성하고, gh-pages.yml 파일을 추가합니다.

mkdir -p .github/workflows
touch .github/workflows/gh-pages.yml

• gh-pages.yml 파일에 다음 내용을 추가합니다.

name: Deploy Hugo site to GitHub Pages
on:
  push:
    branches:
      - master # 또는 메인 브랜치 이름이 다른 경우, 해당 브랜치 이름을 사용하세요
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      - name: Build
        run: hugo --destination docs
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          publish_branch: master

• 이 파일을 커밋하고 푸시합니다.

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow for deploying to GitHub Pages"
git push origin master

Buy me a coffee