CI 파이프라인에서 가장 중요한 두 요소는 결과 관리(Artifacts) 와 속도 최적화(Cache) 이다.
GitHub Actions는 기본적으로 매 실행마다 새로운 VM(클린 환경)을 제공하므로, 작업 결과를 남기거나 재사용하려면 아티팩트와 캐시 구조를 반드시 이해해야 한다.
이 글은 Artifacts, Cache, Job Outputs를 실무 기준으로 분해하여 정확한 개념·구조·용도·최소 예제까지 제공한다.
1. Artifacts: 실행 결과를 안전하게 저장·공유하는 구조
Artifacts는 Workflow 실행 결과물을 저장·다운로드·다른 Job과 공유할 수 있는 기능이다.
예: 빌드 결과, 테스트 리포트, 로그 파일 등.
핵심 목적
- 빌드 결과물을 수동 다운로드
- Job 간 파일 전달
- 테스트 리포트·스크린샷 보존
- 배포 파이프라인에서 산출물 전달
Artifacts는 CI/CD에서 “결과를 남기는” 데 유일한 공식 방식이다.
1.1 최소 업로드 예제
- name: Upload build output
uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/1.2 다운로드 예제
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: build-outputArtifacts는 VM 외부 스토리지에 저장되므로 Job이 달라도 재사용 가능하다.
2. Cache: 의존성 설치를 생략해 CI 속도를 크게 줄이는 기술
GitHub Actions Cache는 파일 기반 캐싱으로, 일반적으로 의존성 설치 최적화에 사용한다.
대표 용도
- npm install / npm ci 속도 단축
- pip / gradle / maven / cargo 캐시
- 빌드 캐시(Webpack, Turborepo 등)
- LFS 포함된 대형 repo 캐시
Artifacts = 결과 저장
Cache = 재사용 가능한 데이터 저장
두 개념은 목적이 명확히 다르다.
2.1 npm 캐시 최소 예제
- name: Cache node modules
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
restore-keys: |
${{ runner.os }}-npm-캐시 원리
key값이 완전히 일치하면 캐시 적중(hit)- 일치하지 않으면 restore-keys의 prefix로 fallback
- 완전히 없으면 miss → 설치 후 캐시 업데이트
실무에서 hashFiles 로 lock 파일을 기준으로 사용해야 한다.
3. Job Outputs: Job 간 데이터 전달(파일이 아닌 텍스트)
Job Outputs는 문자열 기반 데이터 전달용이며, 파일은 아티팩트로 전달해야 한다.
대표 용도:
- 버전 번호 전달
- 테스트 결과 상태 전달
- 빌드 Job → 배포 Job 로 정보 전달
최소 예제
# producer job
jobs:
build:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.ver.outputs.version }}
steps:
- id: ver
run: echo "version=1.2.0" >> $GITHUB_OUTPUT# consumer job
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo "Deploy version ${{ needs.build.outputs.version }}"Job Outputs는 VM 파일 시스템을 공유하지 않으므로 작은 데이터만 전달해야 한다.
4. Dependency Cache 전략: 실무 최적화 핵심
의존성 캐시는 CI 성능 개선의 가장 직접적인 방법이다.
Node 프로젝트 권장 패턴
- name: Cache deps
uses: actions/cache@v4
with:
path: ~/.npm
key: deps-${{ hashFiles('package-lock.json') }}팁:
hashFiles는 lock 파일 기준으로 정확해야 한다.- node_modules 자체 캐싱은 프로젝트마다 비효율적일 수 있다.
- monorepo는 캐시 키를 워크스페이스 단위로 분리해야 한다.
5. Docker 기반 Job + 캐시 활용
Docker Job에서도 캐시는 동일하게 사용 가능하지만, 컨테이너 내부 경로와 호스트 캐시 경로를 정확히 맞춰야 한다.
예시:
container:
image: node:18
steps:
- uses: actions/cache@v4
with:
path: /root/.npm
key: npm-${{ hashFiles('package-lock.json') }}6. Artifacts vs Cache 명확 구분(중요)
| 기능 | Artifacts | Cache |
|---|---|---|
| 목적 | 결과 보존 | 속도 최적화 |
| 용도 | 파일 전달, 다운로드 | 의존성/빌드 데이터 재사용 |
| Job 간 공유 | 가능 | 조건부(캐시 키 일치할 경우) |
| 저장기간 | 기본 90일 | LRU 기반 유지 |
| 저장크기 제한 | 5GB | 10GB |
| 재실행 영향 | 없음 | 캐시 hit 여부에 따라 속도 차이 |
Artifacts는 “결과 보존용”이고 Cache는 “속도 개선용”이다.
서로 대체 가능하지 않다.
7. 실무형 CI 최적화 패턴: Test → Build → Artifact 저장
name: optimized-ci
on: push
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test
build:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist/이 구조는 대부분의 Node 기반 프로젝트에서 그대로 사용 가능하다.
8. 보안 및 오해하기 쉬운 포인트
1) Artifacts는 민감 정보 저장에 적합하지 않다.
- 다운로드 가능
- 영구 암호화되지 않음
- 접근 제어가 제한적
Secrets는 절대 artifacts로 남기지 말아야 한다.
2) Cache는 보안 기능이 아니다.
패키지 캐싱은 사용자·프로젝트 전용 영역에서 동작하지만 보안 데이터 저장 용도는 아니다.
3) Job Outputs는 대용량 전달 불가.
문자열 기반이며 몇 KB 수준만 전달이 적합하다.
4) 아티팩트를 Job 간 공유하는 것을 “캐시”라고 착각.
두 기능은 완전히 목적이 다르다.
9. 핵심 개념 정리
- Artifacts: 실행 결과물 저장·다운로드·Job 간 파일 공유
- Cache: 의존성·빌드 데이터 재사용으로 CI 속도 개선
- Job Outputs: 작은 문자열 기반 데이터 전달
- Dependency Cache: npm/pip/gradle 등 설치 최적화 핵심
- CI Optimization: Artifacts로 결과 관리 + Cache로 속도 개선
아티팩트는 “결과 관리”, 캐시는 “성능 최적화”라는 목적 분리가 중요하다.
10. 실수하기 쉬운 포인트
- artifacts를 캐시 대용으로 사용 → 성능 개선 불가
- cache key를 고정값으로 설정 → 항상 miss 발생
- node_modules 자체 캐싱 → 충돌·용량 증가
- Job Outputs로 파일 전달 시도 → 즉시 실패
- secrets를 artifact에 포함해 저장 → 보안 사고
- restore-keys를 잘못 구성해 fallback이 불가능한 상태 발생
Artifacts와 Cache는 GitHub Actions CI/CD의 핵심 성능·관리 기능이며, 두 구조를 정확히 이해하면 파이프라인 속도와 안정성을 동시에 확보할 수 있다.
