GitHub Action 관련 문제들 정리

👋 이 포스팅에서 다룰 내용

GitHub Actions로 12시간마다 블로그 자동 새로고침하기에서는 12시간마다 GitHub Pages를 자동으로 새로고침하는 방법을 다뤘습니다.
하지만 그대로 따라 했을 때 잘 작동하지 않는 경우가 종종 있습니다.
이번 글에서는 자주 발생하는 문제와 해결 방법을 정리해보겠습니다.

---

🧩 1️⃣ GitHub Action에서 build 워크플로우가 생성되지 않음

GitHub Actions로 12시간마다 블로그 자동 새로고침하기 포스팅 대로 build.yml을 만들어
Action 탭 → build → Run workflow를 눌러도 작동하지 않는 경우가 있습니다.

이럴 때는 단순히 파일 이름을
build.yml → build-temp.yml
로 변경해보세요.

GitHub에서 워크플로우 파일을 인식할 때 캐시 오류가 발생하는 경우가 있는데, 파일명을 바꾸면 정상 인식됩니다.

---

⚙️ 2️⃣ build 워크플로우가 실행되어도 예약 포스팅이 반영되지 않음

GitHub 블로그를 운영하다 보면, 포스팅을 날짜별로 예약해도
예약 날짜가 되어도 자동으로 게시되지 않는 문제를 겪을 수 있습니다.

이유는 GitHub Pages가 사이트를 빌드할 때
내부적으로 캐시 폴더를 생성하고,
그 안에 현재 날짜 기준으로 유효한 포스트만 포함시키기 때문입니다.

즉, 예약일이 되어도 새로 빌드가 트리거되지 않으면
캐시에 포함되지 않아 페이지에 표시되지 않습니다.

✅ 해결법:
정기적으로 사이트를 다시 빌드하도록 GitHub Actions에 스케줄(job refresh) 설정을 추가해야 합니다.

---

🧭 3️⃣ GitHub Pages 배포 방식을 변경하기

기본 설정은 Deploy from a branch로 되어 있으며,
이 방식은 GitHub이 내부적으로 제공하는 기본 워크플로우(pages-build-deployment)를 사용합니다.

하지만 이 방식은 커스터마이징이 어렵고,
수동 제어나 다양한 세부 설정이 불가능하다는 단점이 있습니다.

따라서 위와 같이 “GitHub Actions”로 변경하는 것을 추천합니다.

위 사진의 pages-build-deployment는 GitHub의 기본 내장 Action입니다.
우리는 그 위에 build.yml을 직접 작성하여 더 세밀하게 제어하고 싶습니다.

---

🛠️ 4️⃣ build.yml 직접 수정하기

Minimal Mistakes 테마 기본 build.yml에는
report-build-status나 deploy 단계가 포함되어 있지 않습니다.

따라서 아래와 같이 직접 작성해주는 것이 좋습니다 👇

💡 참고: 추후 Algolia API를 연동하여 개인 블로그 검색 분석 기능도 추가할 예정입니다.

name: build

on:
  push:
    branches:
      - master
  schedule:
    - cron: '0 0 * * *'   # ⏱ 매일 00시에 실행
  workflow_dispatch:
  repository_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'

      - name: Setup cache for Bundler
        id: cache
        uses: actions/cache@v4
        with:
          path: |
            docs/Gemfile.lock
            docs/vendor/bundle
          key: $-bundler-$
          restore-keys: |
            $-bundler-

      - name: Install Bundler
        working-directory: .
        run: |
          bundle config set path vendor/bundle
          bundle install --jobs=4 --retry=3
          bundle clean

      - name: Build Jekyll site
        run: bundle exec jekyll build -d _site

      - name: Upload build artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site
          name: github-pages  # ✅ 반드시 이 이름으로 지정해야 함

  report-build-status:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Report build result
        run: echo "✅ Build completed for commit $" >> $GITHUB_STEP_SUMMARY

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

---

이렇게 하면 Actions가 정상적으로 실행되는 것을 확인할 수 있습니다 ✅

추가로 workflow_dispatch: 설정을 통해
원할 때마다 수동으로 새로고침(refresh) 할 수도 있습니다.

---

마무리

12시간 마다 자동 refresh와 수동으로 refresh 하는 방법에 대해서 포스팅을 하였습니다.
다음 포스팅은 Algolia API에 대해서 설명하도록 하겠습니다.