Checkout Error Fix Plan

문제 분석

에러 메시지

Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under
'/home/runner/work/newsfork-seeds/newsfork-seeds/.github/actions/setup-project'.
Did you forget to run actions/checkout before running your local action?

발생 위치

• Job: validate (Pre-deployment Validation)
• Step: Setup Project (Composite Action 사용)
• Composite Action: ./.github/actions/setup-project

---

🔍 근본 원인 분석

GitHub Actions의 Local Action 동작 방식

1. Local Composite Action 사용 전제 조건

   • Local action을 사용하려면 먼저 repository를 checkout해야 함
   • Composite Action 파일(action.yml)이 repository 내부에 있기 때문
   • Checkout 없이는 action 파일에 접근할 수 없음

2. 현재 구조의 문제점

   jobs:
     validate:
       steps:
         - name: Setup Project
           uses: ./.github/actions/setup-project  # ❌ Checkout 전에 사용 시도

   .github/actions/setup-project/action.yml

   runs:
     using: 'composite'
     steps:
       - name: Checkout  # ❌ 이미 Composite Action 내부에 있음
         uses: actions/checkout@v4

3. 문제의 핵심

   • Composite Action을 사용하기 전에 checkout이 필요함
   • 하지만 현재는 Composite Action 내부에 checkout이 있음
   • 이는 닭과 달걀 문제: Action을 사용하려면 checkout이 필요하지만, checkout은 Action 내부에 있음

---

✅ 해결 방안

방안 1: Job에서 먼저 Checkout 실행 (권장) ⭐

개념

• 각 job에서 Composite Action을 사용하기 전에 먼저 actions/checkout@v4 실행
• setup-project action에서 checkout step 제거
• setup-project action은 checkout 이후의 setup만 수행

장점

• ✅ GitHub Actions의 표준 패턴
• ✅ 명확한 의존성 (checkout → action 사용)
• ✅ 다른 Composite Actions도 동일한 패턴 적용 가능
• ✅ 디버깅 용이

단점

• ⚠️ 각 job에서 checkout step 추가 필요 (하지만 이는 표준 패턴)

구현 구조

Before (현재 - 문제 있음):

jobs:
  validate:
    steps:
      - name: Setup Project
        uses: ./.github/actions/setup-project  # ❌ Checkout 전에 사용

After (수정 후):

jobs:
  validate:
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Project
        uses: ./.github/actions/setup-project  # ✅ Checkout 후 사용

setup-project/action.yml 수정:

# Checkout step 제거
runs:
  using: 'composite'
  steps:
    # ❌ 제거: - name: Checkout
    # ❌ 제거:   uses: actions/checkout@v4

    - name: Setup Environment
      shell: bash
      run: |
        chmod +x .github/scripts/setup.sh
        ./.github/scripts/setup.sh
      env:
        GITHUB_SHA: ${{ github.sha }}
        # ...

    - name: Setup pnpm
      uses: pnpm/action-setup@v4
      # ...

---

방안 2: Checkout 전용 Composite Action 분리 (대안)

개념

• checkout-repo action 생성 (checkout만 수행)
• setup-project action은 checkout 없이 setup만 수행
• Job에서 두 action을 순차적으로 사용

장점

• ✅ 명확한 책임 분리
• ✅ 재사용 가능한 checkout action

단점

• ⚠️ 추가 action 생성 필요
• ⚠️ 두 step으로 분리되어 복잡도 증가

구현 구조

jobs:
  validate:
    steps:
      - name: Checkout repository
        uses: ./.github/actions/checkout-repo

      - name: Setup Project
        uses: ./.github/actions/setup-project

---

방안 3: Inline Steps로 변경 (비권장)

개념

• Composite Action 사용 포기
• 각 job에서 setup steps를 직접 작성

단점

• ❌ 중복 코드 증가 (원래 개선 목적과 반대)
• ❌ 유지보수성 저하
• ❌ 코드 품질 저하

---

🎯 권장 해결 방안: 방안 1

선택 이유

1. GitHub Actions 표준 패턴

   • 공식 문서에서 권장하는 방식
   • 다른 프로젝트에서도 널리 사용

2. 명확한 의존성

   • Checkout → Action 사용 순서가 명확
   • 디버깅이 쉬움

3. 최소 변경

   • setup-project action에서 checkout만 제거
   • 각 job에 checkout step 추가 (표준 패턴)

4. 확장성

   • 다른 Composite Actions도 동일한 패턴 적용 가능

---

📋 상세 구현 계획

Phase 1: setup-project Action 수정

변경 사항

1. setup-project/action.yml에서 checkout step 제거
2. 나머지 setup steps는 유지

수정 전:

runs:
  using: 'composite'
  steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Setup Environment
      # ...

수정 후:

runs:
  using: 'composite'
  steps:
    # Checkout은 job에서 먼저 실행됨

    - name: Setup Environment
      shell: bash
      run: |
        chmod +x .github/scripts/setup.sh
        ./.github/scripts/setup.sh
      env:
        GITHUB_SHA: ${{ github.sha }}
        GITHUB_REPOSITORY: ${{ github.repository }}
        GITHUB_RUN_ID: ${{ github.run_id }}
        GITHUB_RUN_NUMBER: ${{ github.run_number }}

    - name: Setup pnpm
      uses: pnpm/action-setup@v4
      with:
        version: ${{ inputs.pnpm-version }}

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: "pnpm"

    - name: Install dependencies
      shell: bash
      run: pnpm install --frozen-lockfile

---

Phase 2: deploy.yml 수정

변경 대상 Jobs

• validate
• provision
• deploy
• deploy-production

각 Job에 추가할 Step

steps:
  - name: Checkout repository
    uses: actions/checkout@v4
    with:
      fetch-depth: 0  # Full history for git info

  - name: Setup Project
    uses: ./.github/actions/setup-project

---

Phase 3: 영향받는 Composite Actions 확인

확인 필요

• ✅ setup-project: checkout 제거 필요
• ✅ determine-environment: checkout 불필요 (이미 job에서 checkout 후 사용)
• ✅ setup-tmate: checkout 불필요 (이미 job에서 checkout 후 사용)

---

📊 변경 영향 분석

변경되는 파일

1. .github/actions/setup-project/action.yml

   • Checkout step 제거
   • 나머지 steps 유지

2. .github/workflows/deploy.yml

   • 4개 job에 checkout step 추가
   • 각 job의 첫 번째 step으로 추가

영향받는 Jobs

• validate: checkout step 추가
• provision: checkout step 추가
• deploy: checkout step 추가
• deploy-production: checkout step 추가

영향받지 않는 항목

• ✅ determine-environment action: 변경 불필요
• ✅ setup-tmate action: 변경 불필요
• ✅ 다른 스크립트들: 변경 불필요

---

✅ 검증 계획

1. 로컬 검증

• setup-project/action.yml 문법 검사
• deploy.yml 문법 검사
• Checkout step이 모든 job에 추가되었는지 확인

2. GitHub Actions 검증

• validate job 실행 확인
• provision job 실행 확인
• deploy job 실행 확인
• deploy-production job 실행 확인

3. 기능 검증

• Checkout이 정상적으로 실행되는지 확인
• Setup steps가 정상적으로 실행되는지 확인
• Composite Actions가 정상적으로 사용되는지 확인

---

🚨 주의사항

1. Checkout Step 위치

• ✅ 반드시 Composite Action 사용 전에 실행
• ✅ 각 job의 첫 번째 step으로 배치

2. Checkout 설정

• ✅ fetch-depth: 0 유지 (git 정보 필요)
• ✅ 다른 설정은 기본값 사용

3. Composite Action 내부 Checkout

• ❌ Composite Action 내부에서 checkout 금지
• ✅ Job에서 먼저 checkout 후 action 사용

---

📝 구현 체크리스트

setup-project Action 수정

• Checkout step 제거
• 나머지 steps 유지
• action.yml 문법 검사

deploy.yml 수정

• validate job에 checkout step 추가
• provision job에 checkout step 추가
• deploy job에 checkout step 추가
• deploy-production job에 checkout step 추가

검증

• 로컬 문법 검사
• GitHub Actions 테스트
• 모든 job 정상 실행 확인

---

🎯 예상 결과

Before (에러 발생)

jobs:
  validate:
    steps:
      - name: Setup Project
        uses: ./.github/actions/setup-project  # ❌ Checkout 전에 사용

에러: Can't find 'action.yml'...

After (정상 동작)

jobs:
  validate:
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Project
        uses: ./.github/actions/setup-project  # ✅ Checkout 후 사용

결과: 정상 실행 ✅

---

📚 참고 자료

GitHub Actions 공식 문서

• Creating a composite action
• Using actions in your workflow

관련 이슈

• actions/checkout#1498
• community/discussions#67904

---

기획 완료 일시: 2026-01-28
우선순위: 🔴 Critical (즉시 수정 필요)
예상 작업 시간: 15분
난이도: 낮음