자동 빌드·자동 테스트 고급 옵션

자동 빌드·자동 테스트 고급 옵션 (Advanced options for autobuild and autotest)

자동 빌드와 자동 테스트 과정을 커스터마이즈할 수 있는 빌드·테스트·푸시 명령 오버라이드와 빌드 훅(hook) 사용법을 배워볼게요.

출처: 문서

본문

경고: Docker Hub Automated Builds는 더 이상 사용되지 않는(deprecated) 기능이에요. 2027년 4월 1일에 완전히 퇴역할 예정이에요. 지원되는 CI/CD 워크플로우로 이동하려면 마이그레이션 가이드를 확인해요.

참고: 자동 빌드에는 Docker Pro, Team, Business 구독이 필요해요.

다음 옵션들을 사용하면 자동 빌드와 자동 테스트 과정을 커스터마이즈할 수 있어요.

빌드·테스트용 환경 변수

빌드 과정이 여러 유틸리티 환경 변수를 설정해 두고, 이것들은 자동 빌드, 자동 테스트, 그리고 훅 실행 중에 사용할 수 있어요.

참고: 이 환경 변수들은 빌드·테스트 프로세스에서만 사용할 수 있고, 서비스의 실행 환경에는 영향을 주지 않아요.

SOURCE_BRANCH: 현재 테스트 중인 브랜치 또는 태그의 이름.
SOURCE_COMMIT: 테스트 중인 커밋의 SHA1 해시.
COMMIT_MSG: 테스트·빌드 중인 커밋의 메시지.
DOCKER_REPO: 빌드 중인 Docker 저장소의 이름.
DOCKERFILE_PATH: 현재 빌드 중인 Dockerfile.
DOCKER_TAG: 빌드 중인 Docker 저장소 태그.
IMAGE_NAME: 빌드 중인 Docker 저장소의 이름과 태그. (DOCKER_REPO:DOCKER_TAG의 조합이에요.)

자동 테스트에서 docker-compose.test.yml 파일에 이 빌드 환경 변수들을 사용한다면, 아래와 같이 sut 서비스의 environment에 선언해줘야 해요.

services:
  sut:
    build: .
    command: run_tests.sh
    environment:
      - SOURCE_BRANCH

빌드·테스트·푸시 명령 오버라이드

Docker Hub는 자동 빌드·테스트 과정에서 훅(hooks)을 사용해 build, test, push 명령을 오버라이드하고 커스터마이즈할 수 있게 해줘요. 예를 들어 빌드 과정에서만 사용되는 빌드 인자를 설정하는 build 훅을 사용할 수 있어요. 또한 이 명령들 사이에서 동작을 수행하는 커스텀 빌드 단계 훅(custom build phase hooks)도 설정할 수 있답니다.

중요: 이 훅들은 주의해서 사용해요. 훅 파일의 내용이 기본 docker 명령을 대체하기 때문에, 훅 파일에 빌드·테스트·푸시 명령을 포함해야 해요. 그렇지 않으면 자동 빌드 과정이 완료되지 않아요.

이 단계들을 오버라이드하려면 소스 코드 저장소에서 Dockerfile과 같은 디렉터리 레벨에 hooks라는 폴더를 만들어요. hooks/build, hooks/test, 또는 hooks/push라는 파일을 만들고, 빌더 프로세스가 실행할 수 있는 명령(docker 명령이나 #!/bin/bash로 적절히 접두사 붙인 bash 명령)을 포함해요. 이 훅들은 Perl이나 Python 같은 인터프리터, git이나 curl 같은 유틸리티를 포함하는 Ubuntu 인스턴스에서 실행돼요. 사용 가능한 인터프리터와 유틸리티의 전체 목록은 Ubuntu 문서를 참고해요.

커스텀 빌드 단계 훅 (Custom build phase hooks)

훅을 만들어 빌드 과정의 단계 사이에 커스텀 명령을 실행할 수 있어요. 훅을 사용하면 autobuild와 autotest 프로세스에 추가 지시를 제공할 수 있어요.

소스 코드 저장소에서 Dockerfile과 같은 디렉터리 레벨에 hooks라는 폴더를 만들고, 그 폴더에 훅을 정의하는 파일을 놓아요. 훅 파일은 #!/bin/bash로 적절히 접두사 붙인 docker 명령과 bash 명령을 모두 포함할 수 있어요. 빌더는 각 단계 전후에 파일의 명령을 실행해요.

다음 훅들을 사용할 수 있어요:

hooks/post_checkout
hooks/pre_build
hooks/post_build
hooks/pre_test
hooks/post_test
hooks/pre_push (빌드 규칙 또는 자동 빌드 실행 시에만 사용)
hooks/post_push (빌드 규칙 또는 자동 빌드 실행 시에만 사용)

빌드 훅 예시

"build" 단계를 오버라이드해 변수 설정하기

Docker Hub는 훅 파일이나 자동 빌드 인터페이스에서 빌드 환경 변수를 정의할 수 있게 해주고, 이 변수들을 훅에서 참조할 수 있어요. 다음 예시는 Docker Hub 빌드 설정으로 정의한 변수 값을 기반으로 docker build 인자를 사용해 CUSTOM 변수를 설정하는 build 훅이에요. $DOCKERFILE_PATH는 빌드하려는 Dockerfile의 이름을 지정하는 변수이고, $IMAGE_NAME은 빌드 중인 이미지의 이름이에요.

$ docker build --build-arg CUSTOM=$VAR -f $DOCKERFILE_PATH -t $IMAGE_NAME .

중요: hooks/build 파일은 빌더가 사용하는 기본 docker build 명령을 대체하므로, 훅에 유사한 build 명령을 포함해야 해요. 그렇지 않으면 자동 빌드가 실패해요. Docker 빌드 타임 변수에 대해 더 알아보려면 docker build 문서를 참고해요.

여러 저장소에 푸시하기

기본적으로 빌드 과정은 빌드 설정이 구성된 저장소에만 이미지를 푸시해요. 같은 이미지를 여러 저장소에 푸시해야 한다면 post_push 훅을 설정해 추가 태그를 만들고 더 많은 저장소에 푸시할 수 있어요.

$ docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
$ docker push $DOCKER_REPO:$SOURCE_COMMIT

소스 저장소 또는 브랜치 클론

Docker Hub가 소스 코드 저장소에서 브랜치를 가져올 때 shallow clone을 수행해요. 즉 지정된 브랜치의 최신 커밋(tip)만 클론해요. 이 방식은 저장소에서 필요한 데이터 전송량을 최소화하고, 필요한 최소한의 코드만 가져오기 때문에 빌드를 빠르게 해주는 장점이 있어요.

따라서 post_push 훅처럼 다른 브랜치에 의존하는 커스텀 작업을 수행해야 할 경우, 아래 중 하나를 수행하지 않으면 그 브랜치를 체크아웃할 수 없어요.

다음과 같이 대상 브랜치의 shallow 체크아웃을 얻을 수 있어요:

$ git fetch origin branch:mytargetbranch --depth 1

fetch에 --unshallow 플래그를 사용해 전체 Git 기록을 가져오는(unshallow) 방법도 있어요. 단, 시간이 오래 걸리고 많은 데이터를 이동시킬 수 있어요:

$ git fetch --unshallow origin

자동 빌드·자동 테스트 고급 옵션