GIT/Github

GitHub Actions에서 actions/checkout@v4

Rainbound-IT 2025. 9. 11. 09:38
반응형

CI/CD를 GitHub Actions로 구성할 때 가장 자주 보이는 스텝이 바로 다음과 같습니다:

 
- name: Checkout uses: actions/checkout@v4

많은 분들이 그냥 “필수니까 넣는 것” 정도로 알고 계신데요, 사실 이 스텝은 런너 환경에서 우리가 작성한 레포지토리 소스 코드를 가져오는 핵심 역할을 합니다. 이번 글에서는 checkout이 정확히 어떤 작업을 하고, 어떤 흐름으로 동작하는지 정리해 보겠습니다.

왜 Checkout이 필요한가?

GitHub Actions의 잡(job)은 ubuntu-latest 같은 깨끗한 런너 환경에서 실행됩니다.
즉, 기본 상태에서는 소스 코드 파일이 하나도 없는 빈 머신이에요.

하지만 빌드, 테스트, 배포를 하려면 레포지토리의 코드가 반드시 필요합니다:

  • Docker 빌드 → Dockerfile과 애플리케이션 소스
  • 테스트 실행 → 코드와 테스트 스크립트
  • 배포 → Helm 차트, Terraform 코드, K8s 매니페스트 등

이때 코드를 내려주는 스텝이 바로 actions/checkout입니다.

Checkout이 가져오는 것

기본 설정이라면:

  • 현재 워크플로우를 트리거한 리포지토리
  • 실행 시점의 정확한 커밋 SHA
  • 기본 fetch-depth: 1 → 해당 커밋만 가져오는 얕은 클론

옵션을 주면 더 많은 것을 가져올 수도 있습니다:

  • fetch-depth: 0 → 전체 히스토리
  • ref: main / 특정 태그 → 원하는 브랜치/태그/커밋
  • submodules: true → 서브모듈까지
  • lfs: true → Git LFS 파일까지
  • repository: org/other-repo → 다른 리포지토리도 가능

내부 동작 흐름

checkout이 내부적으로 수행하는 단계는 아래와 같습니다:

  1. 입력 파라미터 확인
    레포지토리, 브랜치/커밋, fetch-depth, submodules, LFS 여부 등
  2. 작업 디렉터리 준비
    런너의 $GITHUB_WORKSPACE를 초기화
    (필요 시 path 옵션으로 하위 폴더 지정 가능)
  3. Git 초기화 & 원격 등록
  4.  
    git init git remote add origin https://x-access-token:<token>@github.com/<repo>.git git config --global --add safe.directory <workspace>
  5. fetch & checkout
  6.  
    git fetch --no-tags --prune --depth=1 origin <ref> git checkout --progress --force <commit/branch/tag>
  7. 옵션 처리
    • submodules: true → git submodule update --init --recursive
    • lfs: true → git lfs fetch && git lfs checkout
  8. 후처리
    필요 시 추적 안 되는 파일 정리, 인증 정보 정리

결과적으로 그 시점의 레포지토리 코드가 런너에 준비됩니다.

실제 워크플로우 흐름 예시

예를 들어, 다음과 같은 deploy 잡이 있다고 해봅시다:

 
jobs: deploy: permissions: id-token: write contents: read runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Build Docker Image run: docker build -t my-service:latest . - name: Push to ECR run: docker push my-service:latest

여기서:

  1. Checkout → Dockerfile과 소스 코드를 내려받음
  2. Build Docker Image → 내려받은 코드 기반으로 이미지 빌드
  3. Push to ECR → AWS ECR에 업로드

만약 Checkout 스텝이 없다면? → docker build 단계에서 “Dockerfile 없음” 오류로 실패합니다.

요약

  • actions/checkout@v4는 GitHub Actions에서 코드 빌드·배포를 하기 위해 가장 먼저 실행해야 하는 필수 단계입니다.
  • 기본은 트리거된 커밋 하나만 가져오지만, 옵션으로 히스토리, 서브모듈, LFS, 다른 리포지토리까지 유연하게 가져올 수 있습니다.
  • 내부적으로는 git init → remote add → fetch → checkout 흐름으로 동작합니다.
  • CI/CD 워크플로우의 거의 모든 빌드/배포 잡에서 사용되는 가장 기본적인 액션입니다.

👉 정리하면, checkout은 단순히 "소스코드 가져오기"가 아니라 워크플로우의 나머지 단계를 가능하게 만드는 시작점입니다.

반응형