[#22] README 자동 생성 GitHub Action 적용

[kenshin579]

개요

blog-v2.advenoh.pe.kr 프로젝트의 README 자동 생성 GitHub Action을 현재 프로젝트에 적용했습니다.

주요 변경사항

1. GitHub Actions 워크플로우 추가

• 파일: .github/workflows/generate-readme.yml
• 트리거: main 브랜치 푸시 시 (README.md 변경 제외)
• 동작: Docker 컨테이너로 README 생성 후 자동 PR 생성

2. 워크플로우 설정

• 브랜치: main
• Docker 이미지: kenshin579/readme-generator:latest
• 환경변수:
  • BLOG_URL: https://investment.advenoh.pe.kr
  • CONTENT_DIR: contents
  • WORKSPACE_DIR: /workspace

3. 무한 루프 방지

• paths-ignore: - 'README.md' 설정으로 README.md만 변경 시 워크플로우 트리거 방지

테스트 결과

✅ Phase 1: 로컬 테스트

• Docker 이미지 실행 성공 (95개 포스트 ��식)
• README.md UTF-8 인코딩 확인
• 카테고리별 콘텐츠 인식 확인 (Etc, Etf, Stock, Weekly)
• 블로그 URL 정상 적용

✅ Phase 2: 워크플로우 구현

• GitHub Actions 워크플로우 파일 생성
• 브랜치 및 환경변수 설정 확인

다음 단계 (Phase 3 & 4)

이 PR 병합 후 자동으로 테스트됩니다:

• 워크플로우 "Generate TOC in README" 실행 확인
• readme-patches 브랜치 자동 생성 확인
• 자동 PR 생성 및 라벨링 확인
• 무한 루프 방지 동작 확인

관련 이슈

Closes #22

커밋 내역

1. README 자동 생성 GitHub Action 적용
2. TODO 파일 완료 상태로 업데이트
3. GitHub Actions 워크플로우 진단 경고 수정

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for investmentadvenoh ready!

Name	Link
🔨 Latest commit	3b1e367
🔍 Latest deploy log	https://app.netlify.com/projects/investmentadvenoh/deploys/69068e84fb6ae500085f0dd5
😎 Deploy Preview	https://deploy-preview-23--investmentadvenoh.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[claude]

PR Review: README 자동 생성 GitHub Action 적용

전반적인 평가

이 PR은 README 자동 생성 기능을 성공적으로 도입하는 좋은 작업입니다. 로컬 테스트를 거쳐 워크플로우를 구현했으며, 문서화도 잘 되어 있습니다. 다만 몇 가지 개선이 필요한 부분이 있습니다.

---

주요 이슈 및 개선 사항

🔴 Critical Issues

1. GitHub Action 버전 업데이트 필요 (.github/workflows/generate-readme.yml:36)

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v3  # ⚠️ 구버전 사용 중

문제점: peter-evans/create-pull-request@v3는 2021년에 릴리스된 구버전입니다.

권장사항: 최신 버전(v7)으로 업데이트

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v7
  with:
    commit-message: Update README file
    branch: readme-patches
    delete-branch: true
    title: '[AUTO] Update README file'
    body: |
      Update README file
    labels: automated pr
    assignees: kenshin579
    reviewers: kenshin579

장점:

• 보안 패치 및 버그 수정 포함
• GitHub의 새로운 기능 지원
• 더 나은 에러 핸들링

2. 하드코딩된 이메일 주소 (.github/workflows/generate-readme.yml:31)

git config user.email 'kenshin579@hotmail.com'  # ⚠️ 하드코딩

문제점: 이메일이 하드코딩되어 있어 유연성이 떨어집니다.

권장사항: GitHub Actions 컨텍스트 사용

- name: Create commits
  run: |
    echo "username: ${{github.actor}}"
    
    git config user.name "${{github.actor}}"
    git config user.email "${{github.actor}}@users.noreply.github.com"
    git add README.md
    git commit -am "update README file"

또는 GitHub Actions bot 사용:

git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"

3. README.md 링크 불일치 (README.md:8)

현재 [블로그](https://blog.advenoh.pe.kr)에 작성된 내용입니다.

문제점: 링크가 blog.advenoh.pe.kr인데, 환경변수는 investment.advenoh.pe.kr로 설정되어 있습니다.

권장사항: 일관성을 위해 수정

현재 [블로그](https://investment.advenoh.pe.kr)에 작성된 내용입니다.

---

🟡 Medium Priority Issues

4. 커밋 메시지가 한국어 규칙을 따르지 않음 (.github/workflows/generate-readme.yml:33)

.github/git-commit-instructions.md에 따르면 모든 커밋 메시지는 한국어로 작성해야 합니다:

현재:

git commit -am "update README file"

권장:

git commit -am "[자동생성] README 파일 업데이트"

5. 워크플로우 실패 처리 부재

Docker 실행이나 커밋 과정에서 실패할 경우에 대한 처리가 없습니다.

권장사항: 실패 조건 추가

- name: Run README generator
  id: generate
  run: |
    docker run --rm \
      -v ${{ github.workspace }}:/workspace \
      -e WORKSPACE_DIR=/workspace \
      -e CONTENT_DIR=contents \
      -e BLOG_URL=https://investment.advenoh.pe.kr \
      kenshin579/readme-generator:latest
  continue-on-error: false

- name: Check for changes
  id: check_changes
  run: |
    if git diff --quiet README.md; then
      echo "No changes to README.md"
      echo "changed=false" >> $GITHUB_OUTPUT
    else
      echo "README.md has changes"
      echo "changed=true" >> $GITHUB_OUTPUT
    fi

- name: Create commits
  if: steps.check_changes.outputs.changed == 'true'
  run: |
    # ... commit logic

6. PR 본문이 너무 간단함

자동 생성된 PR의 본문에 더 많은 정보를 포함하는 것이 좋습니다.

권장사항:

body: |
  ## 📝 README 자동 업데이트
  
  이 PR은 GitHub Actions에 의해 자동으로 생성되었습니다.
  
  ### 변경사항
  - `contents/` 디렉토리의 마크다운 파일 목차 자동 생성
  - 카테고리별 블로그 포스트 링크 업데이트
  - 업데이트 날짜: ${{ github.event.head_commit.timestamp }}
  
  ### 워크플로우
  - 실행된 워크플로우: [${{ github.workflow }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
  
  **⚠️ 이 PR을 병합하기 전에 생성된 README.md를 확인해주세요.**
  
  🤖 Generated by [README Generator Workflow](.github/workflows/generate-readme.yml)

---

🟢 Good Practices

1. 무한 루프 방지: paths-ignore: - 'README.md' 설정이 올바르게 적용되어 있습니다.
2. 로컬 테스트: Docker 이미지를 로컬에서 먼저 테스트한 것은 훌륭한 접근입니다.
3. 문서화: docs/chores/start/ 폴더에 구현 가이드, TODO 목록을 잘 작성했습니다.
4. 브랜치 전략: readme-patches 브랜치를 사용하여 자동 생성된 변경사항을 별도로 관리하는 것이 좋습니다.
5. delete-branch: true: PR 병합 후 브랜치를 자동 삭제하는 설정이 좋습니다.

---

코드 품질 체크리스트

• 코드가 프로젝트 컨벤션을 따름
• 무한 루프 방지 로직 존재
• 최신 GitHub Actions 버전 사용 (v3 → v7 필요)
• 하드코딩된 값 제거 (이메일 주소)
• README.md 링크 일관성
• 한국어 커밋 메시지 규칙 준수
• ��서화 충분
• 에러 처리 로직 필요

---

보안 검토

1. Docker 이미지: kenshin579/readme-generator:latest 사용

   • ⚠️ latest 태그는 예측 불가능한 변경을 가져올 수 있습니다.
   • 권장: 특정 버전 태그 사용 (예: kenshin579/readme-generator:v1.0.0)
   • 이미지 출처 확인 필요 (Docker Hub에서 검증된 이미지인지)

2. 권한 설정: 워크플로우에 명시적인 권한 설정이 없습니다.

   jobs:
     build:
       runs-on: ubuntu-latest
       permissions:
         contents: write
         pull-requests: write

---

성능 고려사항

1. Docker 실행 시간: 매번 Docker 이미지를 pull하므로 캐싱을 고려할 수 있습니다.
2. 빌드 빈도: main 브랜치에 푸시할 때마다 실행되므로, 빈번한 푸시 시 리소스 소비가 증가할 수 있습니다.

---

테스트 제안

Phase 3, 4 테스트 시 다음 사항을 확인하세요:

1. 무한 루프 방지 테스트

   • README.md만 수정하고 푸시했을 때 워크플로우가 실행되지 않는지 확인

2. 병렬 푸시 시나리오

   • 여러 커밋이 빠르게 푸시될 때 여러 PR이 생성되지 않는지 확인

3. 한글 인코딩 검증

   • 생성된 README.md의 한글이 깨지지 않는지 확인 (UTF-8)

4. 링크 유효성 검증

   • 생성된 모든 링크가 유효한지 확인

---

권장 액션 아이템

우선순위 높음:

1. peter-evans/create-pull-request 액션을 v7로 업데이트
2. 하드코딩된 이메일 주소 제거
3. README.md 링크 수정 (blog.advenoh.pe.kr → investment.advenoh.pe.kr)

우선순위 중간:
4. 한국어 커밋 메시지 규칙 적용
5. 워크플로우 권한 명시적 설정
6. Docker 이미지 버전 고정 (latest → 특정 버전)
7. PR 본문 개선
8. 에러 처리 로직 추가

선택사항:
9. Docker 이미지 캐싱 고려
10. 워크플로우 실행 빈도 최적화

---

결론

전반적으로 잘 작성된 PR이며, README 자동 생성 기능을 도입하는 좋은 첫걸음입니다. 위에 언급한 Critical Issues를 수정하면 프로덕션 환경에 배포해도 안전할 것으로 판단됩니다.

Phase 3, 4 테스트를 진행하면서 실제 동작을 검증하고, 필요시 추가 조정을 권장합니다.

---

리뷰어: Claude Code
리뷰 날짜: 2025-11-01

[claude]

코드 리뷰

PR #23에 대한 상세 리뷰를 진행했습니다.

---

✅ 긍정적인 부분

1. 명확한 목적과 구현

   • README 자동 생성을 위한 GitHub Actions 워크플로우가 잘 구현되었습니다
   • 기존 blog-v2 프로젝트의 검증된 워크플로우를 재사용하여 안정성이 높습니다

2. 무한 루프 방지

   • paths-ignore 설정으로 README.md 변경 시 워크플로우 트리거를 방지하여 무한 루프 위험을 잘 차단했습니다
   • workflow_dispatch 추가로 수동 실행도 가능하게 했습니다

3. 문서화

   • docs/chores/start/ 디렉토리에 상세한 문서를 추가하여 구현 배경, 과정, TODO를 잘 정리했습니다

4. 환경 변수 적절히 설정

   • BLOG_URL이 올바르게 https://investment.advenoh.pe.kr 로 설정되었습니다

[claude]

🔍 개선이 필요한 부분

1. GitHub Actions 버전 업데이트 필요 (중요도: 높음)

파일: .github/workflows/generate-readme.yml:37

peter-evans/create-pull-request@v3은 구버전입니다. 보안 및 기능 개선이 이루어진 최신 버전(v7)을 사용해야 합니다.

권장: peter-evans/create-pull-request@v7로 업데이트

2. 커밋 메시지 규칙 미준수 (중요도: 중간)

파일: .github/workflows/generate-readme.yml:34

현재: git commit -am "update README file"

문제점:

• 프로젝트의 커밋 메시지 규칙을 따르지 않았습니다
• 이슈 번호가 없고 한국어가 아닙니다

권장: git commit -am "[#22] README 자동 생성"

3. README.md 내용 불일치 (중요도: 중간)

파일: README.md:8

현재: 블로그

문제점:

• 실제 블로그 URL은 https://investment.advenoh.pe.kr 입니다
• CLAUDE.md와 환경 변수 설정과 불일치합니다

권장: 블로그로 수정

[claude]

4. 중복된 git add 명령 (중요도: 낮음)

파일: .github/workflows/generate-readme.yml:33-34

git commit -am의 -a 플래그가 이미 모든 변경된 파일을 자동으로 stage하므로 git add README.md가 불필요합니다.

권장: git add를 제거하거나 -a 플래그를 제거

5. PR 제목에 한글 사용 고려 (중요도: 낮음)

파일: .github/workflows/generate-readme.yml:42

프로젝트가 한국어 커밋 메시지를 사용하므로 PR 제목도 한글로 통일하는 것이 일���성 있습니다.

현재: [AUTO] Update README file
권장: [AUTO] README 자동 업데이트

6. 에러 핸들링 부족 (중요도: 중간)

• Docker 실행 실패 시 커밋 단계에서 에러가 발생할 수 있습니다
• README.md에 변경사항이 없을 때도 빈 커밋을 시도할 수 있습니다

git diff --quiet으로 변경사항이 있는지 확인 후 커밋하는 것을 권장합니다.

[claude]

🔒 보안 고려사항

양호한 부분:

• Docker 이미지 출처가 명확합니다 (kenshin579/readme-generator:latest)
• 워크스페이스 권한이 적절히 제한되어 있습니다

개선 제안:

• Docker 이미지를 latest 태그 대신 특정 버전 태그를 사용하는 것이 재현성과 보안 측면에서 더 좋습니다
  • 예: kenshin579/readme-generator:v1.0.0

---

📊 테스트 커버리지

• ✅ 로컬 Docker 테스트 완��
• ✅ UTF-8 인코딩 검증 완료
• ⏳ GitHub Actions 실제 실행 테스트 필요 (Phase 3 & 4)

[claude]

🎯 권장 액션 플랜

머지 전 필수 수정사항:

1. peter-evans/create-pull-request를 v7로 업데이트
2. README.md의 블로그 URL을 https://investment.advenoh.pe.kr 로 수정
3. 커밋 메시지를 한국어 규칙에 맞게 수정

머지 후 개선사항:

1. Phase 3 & 4 테스트 진행 후 결과 공유
2. Docker 이미지 버전을 특정 태그로 고정 고려
3. 에러 핸들링 로직 추가 고려

---

✨ 전체 평가

이 PR은 README 자동 생성이라는 명확한 목표를 달성하기 위해 잘 설계되었습니다. 몇 가지 개선사항이 있지만, 대부분 경미한 수준이며 전체적으로 병합 가능 수준입니다. 위의 필수 수정사항을 반영한 후 병합을 권장합니다.

좋은 작업입니다! 🎉