페이지 누락

개요

클라우드플레어 Pages에서 Hugo 사이트 빌드 시 일부 페이지가 누락되는 문제가 발생할 수 있습니다.

발생 원인

콘텐츠 디렉토리를 특정 경로에 마운트하여 사용하는 경우 발생합니다. 로컬 빌드시에는 마운트가 정상적으로 동작하므로 문제가 되지 않지만, GitHub에 푸시할 때 해당 콘텐츠 디렉토리는 비어있으므로 클라우드플레어 Pages에서 빌드할 때도 포함되지 않습니다.

해결 방안

콘텐츠 디렉토리를 Git 서브모듈로 추가
- 콘텐츠 디렉토리를 별도의 리포지토리로 관리하고 메인 리포지토리에 서브모듈로 포함시켜 관리
콘텐츠 디렉토리를 직접 복사하여 포함
- 로컬에서 콘텐츠 디렉토리를 메인 리포지토리에 복사하여 GitHub에 푸시

서브모듈 관리

서브 모듈 추가

콘텐츠 리포지토리를 별도로 생성
- GitHub에서 새로운 리포지토리를 생성하여 콘텐츠를 관리합니다.
- 예를 들어, docflow라는 리포지토리를 생성합니다.
로컬에서 콘텐츠 리포지토리 초기화 및 푸시
- 로컬 콘텐츠 디렉토리를 콘텐츠 리포지토리로 초기화하고 푸시합니다.

cd docflow
git init
git remote add origin https://github.com/aprofl/docflow.git
git add .
git commit -m "Initial commit for content repository"
git push origin master

메인 프로젝트에 서브모듈로 콘텐츠 리포지토리 추가
- 메인 프로젝트 디렉토리로 이동하여 콘텐츠 리포지토리를 서브모듈로 추가합니다

cd docflow_hugo
# 기존 content 디렉토리 제거
rd /s /q content
git rm -r --cached content
git commit -m "Remove existing content directory"
git push origin master
# 서브모듈로 content 디렉토리 추가
git submodule add https://github.com/aprofl/docflow.git content
git submodule init
git submodule update
git add .gitmodules content
git commit -m "Add content as a submodule"
git push origin master

서브모듈 정보 커밋 및 푸시
- 서브모듈 정보를 포함하여 메인 프로젝트를 커밋하고 푸시합니다.

git add .gitmodules content
git commit -m "Add content as a submodule"
git push origin master

변경 사항 푸시 순서

콘텐츠 리포지토리에 변경 사항이 있을 경우, 해당 리포지토리를 먼저 업데이트하고 푸시합니다.

cd docflow
git add .
git commit -m "Update content"
git push origin master

메인 프로젝트 디렉토리로 이동하여 서브모듈을 최신화합니다.

cd docflow_hugo
git submodule update --remote content

서브모듈 최신화를 반영하여 메인 프로젝트를 커밋하고 푸시합니다

git add content
git commit -m "Update submodule to latest version"
git push origin master

푸시 자동화

개요

GitHub Actions을 이용한 푸시 자동화 방법입니다.
컨텐츠프로젝트가 푸시되면 깃 허브에서 메인프로젝트에 서브모듈을 업데이트 하고, 자동으로 푸시합니다.

깃허브 설정

메인프로젝트의 다음 설정을 변경합니다.
Settings > Actions > General 로 이동하여 다음 항목을 변경하고, Save 합니다.
- Workflow permissions
  - Read and write permissions
- Access
  - Accessible from repositories owned by the user ‘aprofl’

GitHub Personal Access Token 생성 및 시크릿 설정 방법

Personal Access Token 생성
- GitHub 프로필 아이콘을 클릭하고 “Settings"로 이동합니다.
- 좌측 사이드바에서 “Developer settings"를 클릭합니다.
- “Personal access tokens” 메뉴에서 “Fine-grained personal access tokens"를 클릭한 후 “Generate new token” 버튼을 클릭합니다.
- 토큰에 필요한 권한을 설정합니다. (예: repo, workflow)
- “Generate token” 버튼을 클릭하여 토큰을 생성하고, 생성된 토큰을 복사해 둡니다.
토큰 설정
- Repository permissions:
  - Contents: Read and write
  - Metadata: Read-only
- Workflows: Read and write
- 유효 기간은 최대 1년까지 설정 가능합니다.
- “Generate token” 버튼을 클릭하여 토큰을 생성하고, 생성된 토큰을 복사합니다.
토큰을 시크릿으로 추가
- GitHub 리포지토리 페이지에서 “Settings” 탭으로 이동합니다.
- 좌측 사이드바에서 “Secrets and variables"을 클릭한 후 “Actions"를 클릭합니다.
- “New repository secret” 버튼을 클릭합니다.
- Name에 PERSONAL_ACCESS_TOKEN을 입력하고, Secret에 복사한 토큰 값을 입력한 후 “Add secret” 버튼을 클릭합니다.

GitHub Actions 설정

GitHub Actions 워크플로우 파일 생성
- 컨텐츠 프로젝트 루트에 .github/workflows/deploy.yml 파일을 생성합니다.

name: Update main project and trigger build
on:
  push:
    branches:
      - master
jobs:
  update_main_project:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout content repository
      uses: actions/checkout@v2
    - name: Print token (for debugging, remove after use)
      run: echo "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
    - name: Checkout main project repository
      uses: actions/checkout@v2
      with:
        repository: aprofl/aprofl
        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        path: docflow_hugo
    - name: Configure Git
      run: |
        git config --global user.email "tjsufl@gmail.com"
        git config --global user.name "aprofl"        
    - name: Initialize submodules with token
      run: |
        cd docflow_hugo
        git submodule update --init --recursive
        git submodule foreach --recursive "git config --global url.\"https://${{ secrets.PERSONAL_ACCESS_TOKEN }}@github.com\".insteadOf \"https://github.com\""        
    - name: Update submodule URL to use token
      run: |
        cd docflow_hugo
        git config submodule.content.url https://${{ secrets.PERSONAL_ACCESS_TOKEN }}@github.com/aprofl/docflow.git        
    - name: Update content submodule in main project
      env:
        GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
      run: |
        cd docflow_hugo
        git submodule update --remote content
        git add content
        git commit -m "Update content submodule to latest version"
        git push origin master

상세 설명

이벤트 트리거
- master 브랜치에 푸시가 발생하면 이 워크플로우가 트리거됩니다.
작업 설정
- GitHub Actions가 ubuntu-latest 환경에서 실행됩니다.
단계별 설정
- 콘텐츠 리포지토리 체크아웃: actions/checkout@v2를 사용하여 콘텐츠 리포지토리를 체크아웃합니다.
- 메인 프로젝트 리포지토리 체크아웃: actions/checkout@v2를 사용하여 메인 프로젝트 리포지토리를 docflow_hugo 경로에 체크아웃합니다.
- 서브모듈 업데이트: docflow_hugo 디렉토리로 이동하여 서브모듈을 최신 버전으로 업데이트하고, 이를 커밋 및 푸시합니다.

클라우드플레어 설정 업데이트

Cloudflare Pages 설정에서 GITHUB_TOKEN을 사용하도록 설정합니다.

Cloudflare Pages 설정:
- Cloudflare Pages의 프로젝트 설정으로 이동합니다.
- Environment Variables 섹션에서 GITHUB_TOKEN 변수를 추가합니다. 변수 이름: GITHUB_TOKEN 변수 값: GitHub Personal Access Token

서브모듈 URL 업데이트

서브모듈의 URL을 인증 정보를 포함한 형태로 변경합니다.

메인 프로젝트의 .gitmodules 파일 수정:

[submodule "content"]
	path = content
	url = https://<your_token>@github.com/aprofl/docflow.git

Git 설정 파일 업데이트

Windows 명령 프롬프트에서 서브모듈 URL을 인증 정보를 포함한 형태로 설정합니다.

cd docflow_hugo
git submodule deinit -f --all
git submodule update --init --recursive
git submodule foreach --recursive "git config submodule.$name.url https://<your_token>@github.com/aprofl/$name.git"
git submodule update --init --recursive

점검 사항

GitHub Actions 워크플로우가 올바르게 트리거되지 않거나, 메인 프로젝트가 제대로 푸시되지 않는 경우 다음의 내용을 확인합니다.

GitHub Actions 로그 확인
- GitHub 리포지토리의 “Actions” 탭에서 워크플로우가 제대로 실행되었는지 확인합니다.
- 오류 메시지나 실패한 단계가 있는지 확인합니다.
서브모듈 설정 확인: 메인 프로젝트에서 서브모듈이 올바르게 설정되어 있는지 확인합니다.
GitHub Actions 파일 위치 확인: .github/workflows/deploy.yml 파일이 올바른 위치에 있는지 확인합니다.
권한 확인: GITHUB_TOKEN이 제대로 작동하고 있는지, 리포지토리에 대한 쓰기 권한이 있는지 확인합니다.

Buy me a coffee

클라우드 빌드 설정 변경