같은 워크플로우인데 다른 job에서 빌드 결과물을 못 찾은 이유

문제 발생

빌드 job에서 만든 결과물(dist/)을 배포 job에서 그대로 쓰려고 했는데, 배포 job에서 그 폴더가 아예 존재하지 않는다는 에러가 났습니다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build   # dist/ 생성

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ls dist/   # 에러: 그런 파일이나 디렉터리가 없음

원인 분석

GitHub Actions에서 각 job은 서로 다른, 완전히 독립적인 러너(가상 머신 또는 컨테이너)에서 실행됩니다. needs: build로 순서를 보장하더라도, 그건 "build가 끝난 뒤에 deploy가 시작된다"는 실행 순서만 보장할 뿐, 두 job이 같은 파일 시스템을 공유한다는 뜻은 아닙니다. build job의 러너는 작업이 끝나면 그대로 폐기되고, deploy job은 완전히 새로운 깨끗한 러너에서 시작합니다 — 이전 job이 만든 파일이 있을 리 없습니다.

해결 방안

job 사이에 파일을 전달하려면 artifact로 명시적으로 업로드하고 다운로드해야 합니다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist-files
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist-files
          path: dist/
      - run: ls dist/   # 이제 정상적으로 존재함

1. Artifact는 워크플로우 실행이 끝난 뒤에도 일정 기간(기본 90일, retention-days로 조정 가능) 보관되며, GitHub Actions 화면에서 직접 다운로드해 확인할 수도 있습니다.
2. Artifact 업로드/다운로드는 네트워크를 거치므로 어느 정도 시간 비용이 있습니다 — 정말로 다음 job에서 필요한 최소한의 결과물만 업로드하는 것이 좋습니다(예: 전체 node_modules가 아니라 빌드된 결과물만).
3. 반대로 같은 job 안의 여러 step 사이에서는 이런 문제가 없습니다 — 같은 job의 step들은 같은 러너에서 순서대로 실행되므로 파일 시스템을 그대로 공유합니다. 문제는 오직 job과 job 사이에서만 발생합니다.
4. Docker 이미지처럼 아예 다른 방식으로 결과물을 전달하는 경우(레지스트리에 push 후 다른 job에서 pull)라면 artifact 대신 그 방식을 쓰는 것이 더 적합할 수 있습니다 — 상황에 맞는 전달 방식을 선택합니다.

공식 문서

• GitHub Actions Docs: Storing and sharing data with workflow artifacts