Github Page 배포하기 : root에 index.html이 없는 경우 (2) GitHub Actions

이전 글에서 알아보았던 다소 번거로웠던 과정을, GitHub Actions를 사용하여 자동화하는 과정을 정리합니다.

Github Page 배포하기 : root에 index.html이 없는 경우 (1)

 

GitHub Actions란?

GitHub Actions은 GitHub 저장소에 직접 통합된 CI/CD(지속적 통합 및 지속적 배포) 서비스입니다. 코드 변경이 감지될 때마다 자동으로 워크플로우를 실행하여 빌드, 테스트 및 배포 과정을 자동화할 수 있습니다.

1. GitHub Pages 설정

먼저 GitHub Pages 설정을 마쳐야 합니다.

1. 배포할 GitHub 저장소의 Settings 탭을 클릭하여 Pages 로 이동합니다.
2. Source 메뉴에서 gh-pages 브랜치를 선택합니다.

2. GitHub Actions 워크플로우 생성

GitHub Actions를 사용하여 자동 배포 워크플로우를 생성합니다.

1. 저장소의 루트에 .github/workflows 디렉토리를 만듭니다. Github 저장소 페이지에서 직접 생성할 수도 있으며, 후술할 토큰 관련 이유로 저장소 페이지의 Actions 탭에서 직접 생성하는 것을 추천합니다.
2. 해당 디렉토리 안에 deploy.yml 파일을 생성합니다. (파일 이름은 필요한 대로 지정하면 됩니다)

deploy.yml 예시

name: Build and Deploy
on:
  push:
    branches:
      - main  # 메인 브랜치 이름에 맞게 조정

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2 # checkout 라이브러리
    - name: Build
      run: |  # 프로젝트 빌드 스크립트
        npm install
        npm run build
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3 # gh-pages 라이브러리
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public  # 배포할 디렉토리

최상단 부분이 트리거 조건을 나타냅니다. 즉, 이 스크립트는 main 브랜치에 푸시될 때마다 작동합니다.

jobs에서 어떤 일을 수행할지 지정합니다. 예제 코드에서는 먼저 저장소를 체크아웃한 후, 빌드 스크립트를 실행하여 사이트를 빌드합니다. 마지막으로 peaceiris/actions-gh-pages 액션을 사용하여 public 디렉토리의 내용을 gh-pages 브랜치로 푸시합니다.

actions/checkout

GitHub Actions 워크플로우에서 코드 체크아웃(로컬 환경으로 코드를 가져오는 작업)을 수행하기 위해 사용되는 액션(action)입니다. 

보통 GitHub Actions를 사용하여 소프트웨어 개발 및 배포 프로세스를 자동화할 때, 워크플로우 스크립트 내에서 코드 체크아웃 작업이 필요합니다. 코드 체크아웃은 GitHub 레포지토리의 소스 코드를 로컬 환경으로 가져와서 워크플로우에서 사용할 수 있도록 하는 과정입니다.

로컬 환경으로 가져온다는 것은 GitHub 레포지토리에 저장된 소스 코드를 클론 또는 다운로드하여 워크플로우가 실행되는 환경(로컬)으로 가져온다는 뜻입니다. 이렇게 소스코드를 가져오면 워크플로우 스크립트에서 해당 코드를 빌드, 테스트, 배포하는 등의 작업이 가능합니다.

윗부분을 확인해보면 runs-on: ubuntu-latest 라고 되어있는데, 이 부분이 바로 워크플로우가 실행될 가상 환경을 지정하는 부분입니다. 즉, 이 가상환경으로 코드를 가져오기 위해 거의 필수적으로 사용됩니다.

peaceiris/actions-gh-pages

워크플로우에서 GitHub Pages 호스팅을 위한 액션(action)을 제공하는 라이브러리입니다.

이 라이브러리를 사용하면 소스 코드 또는 정적 파일 빌드, GitHub Pages 브랜치로의 배포(일반적으로 gh-pages 브랜치), 자동 푸시 기능을 자동화할 수 있습니다.

3. GitHub Secrets 설정

앞서 작성한 워크플로우 파일에서 secrets.GITHUB_TOKEN을 사용했습니다. 이는 GitHub에서 제공하는 자동 생성 토큰으로, 별도의 설정 없이 사용할 수 있습니다. 만약 개인 토큰을 발급받는 경우에는 별도로 설정해 줄 필요가 있습니다.

4. 변경 사항 커밋 및 푸시

모든 설정이 완료되면, 변경 사항을 저장소에 커밋하고 푸시합니다.

GITHUB_TOKEN을 사용하는 경우 로컬에서 푸시하는 권한이 없다고 떠서 yml 파일을 원격 저장소에서 직접 작성하는 것을 추천합니다.

5. GitHub Actions 확인

GitHub 저장소의 Actions 탭에서 워크플로우가 실행되는 것을 확인할 수 있습니다. 따로 문제가 없다면, public 디렉토리의 내용이 gh-pages 브랜치로 자동으로 배포됩니다.

 

사용된 라이브러리 링크

워크플로우 파일에서 사용된 두 라이브러리는 다음과 같습니다. 공식 문서에 자세한 사용법이 나와있습니다.

github actions checkout

GitHub - actions/checkout: Action for checking out a repo

github actions for github pages

GitHub - peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Stat