도큐사우루스 문서 사이트 만들기 - 3. GitHub Actions 빌드 및 브랜치 생성

이제 도큐사우루스를 이용한 자신의 문서 사이트를 깃헙 페이지를 통한 배포로 무료로 평생 운영되는 사이트를 완성할 수 있다.

서비스 운영 배포가 무료인 GitHub Pages 기술을 활용해서 아무런 비용없이 문서 사이트를 배포하기 전에 만든 문서를 빌드해서 자동으로 특정 브랜치로 배포하는 방법을 살펴보자.

 

도큐사우루스에 대해서는, 설치 부터 운영까지의 내용을 아래와 같이 정리하고 있다.

2024.01.02 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 1. 소개

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 2. 설치 혹은 GitHub Fork로 복사

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 3. GitHub Actions 빌드 및 브랜치 생성

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 4. GitHub Pages 배포 자동화

2024.01.03 - [디지털노마드] - 도큐사우루스 문서 사이트 만들기 - 5. GitHub Pages 도메인 연동하기

2024.01.11 - [도큐사우루스] - 도큐사우루스 문서 사이트 만들기 - 6. 다국어 처리

 

자 이제, 아주 쉽게 포크로 클론해서 1분만에 설치한 도큐사우루스 사이트를 빌드, 생성, 배포되도록 설정을 해보자.

GitHub Actions 로 빌드

깃헙액션을 통해 해당 브랜치로 빌드된 정적 페이지들이 자동 배포되도록 수정한다.

게다가 깃헙페이지를 통해 자동으로 해당 주소로 서비스가 운영되도록 한다.

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

 

깃헙 액션을 이용하여 아주 간단하게 배포할 수 있다. 아래 내가 사용한 스크립트만 잘 변경해서 올리면 끝이다.

작업 디렉토리에서 .github\workflows 폴더를 만들고 그 아래에 deploy.yml 이라는 파일을 만들어서 아래 코드를 입력해 넣으면 끝!

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

permissions:
  contents: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm
          # cache-dependency-path: my-website/package-lock.json

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Build output to publish to the `gh-pages` branch:
          publish_dir: ./build

 

gh-pages 브랜치로 생성된 정적 페이지들이 배포되고, GitHub Pages에서 원하는 도메인 주소를 링크해두면 자신만의 문서 시스템을 갖게 되는 것이다.

 

원래 소스는 여기서 살펴볼 수 있다. 

https://docusaurus.io/docs/deployment#docusaurusconfigjs-settings

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

permissions:
  contents: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn build

      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Build output to publish to the `gh-pages` branch:
          publish_dir: ./build
          # The following lines assign commit authorship to the official
          # GH-Actions bot for deploys to `gh-pages` branch:
          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
          # The GH actions bot is used by default if you didn't specify the two fields.
          # You can swap them out with your own user credentials.
          user_name: github-actions[bot]
          user_email: 41898282+github-actions[bot]@users.noreply.github.com

 

원본은 yarn으로 되어 있고, 내가 수정한 것은 npm 으로 되어있는데 머든 관계없다.

일단 이 코드가 잘 돌아가면 먼가 푸시할때 마다 (문서 변경, 생성, 등등등) 이 액션 코드가 수행되는데 빌드를 통해 정적 웹 페이지 사이트를 만들고 gh-pages 브랜치로 배포하는 역할을 한다.

아무런 비용없이 이런 고급 CI 기법을 사용할 수 있다는 것이 경이롭다 :)

 

직접 파일로 만들어도 되고, 아니면 아래 그림처럼 저장소에 "Actions" 탭에서 New workflow 를 선택하고 생성해도 된다.

깃헙 액션 워크플로 만들기

 

 

(추가) CNAME 생성 - 커스텀도메인 사용시

⭐️ Add CNAME file cname

To add the CNAME file, we can set the cname option. Alternatively, put your CNAME file into your publish_dir. (e.g. public/CNAME)

For more details about the CNAME file, read the official documentation: Managing a custom domain for your GitHub Pages site - GitHub Docs

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    cname: github.com

 

gh-pages 브랜치 생성 확인

아무튼 문제가 없다면 자신의 저장소에 gh-pages 브랜치가 생성되어 있음을 볼 수 있다.

gh-pages 브랜치 생성

 

GitHub Actions 에러 메시지 확인

혹시 에러가 발생하면 아래처럼 찾아가보면 에러 코드를 보면서 금방 수정할 수 있을듯 구글신이 도와주실꺼에요 :)

깃헙 액션 실행 오류

어떤 파일을 찾지 못해서 npm ci 가 실패한 경우였다. 폴더 위치나 패스를 맞춰주어서 해결!