자동 빌드 설정하기

자동 빌드 설정하기 (Set up automated builds)

Docker Hub 저장소에서 소스 제공자에 코드를 푸시할 때마다 이미지를 자동으로 빌드하도록 구성하는 전체 과정을 배워볼게요.

출처: 문서

본문

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

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

자동 빌드 구성하기

Docker Hub에서 저장소를 구성해 소스 제공자에 새 코드를 푸시할 때마다 이미지를 자동으로 빌드하게 할 수 있어요. 자동 테스트를 구성했다면 새 이미지는 테스트가 성공할 때만 푸시돼요.

  1. Docker Hub 에서 My Hub > Repositories 로 이동하고 저장소를 선택해 세부 정보를 봐요.

  2. Builds 탭을 선택해요.

  3. 이미지 소스 코드가 저장된 위치에 연결할 GitHub 또는 Bitbucket 를 선택해요.

    참고: 코드 저장소 서비스를 연결하도록 설정 페이지로 리디렉션될 수 있어요. 그 외에 기존 자동 빌드의 빌드 설정을 편집하는 경우 Configure automated builds 를 선택해요.

  4. Docker 이미지를 빌드할 소스 저장소를 선택해요.

    참고: 소스 코드 제공자에서 조직이나 사용자를 지정해야 할 수 있어요. 사용자를 선택하면 Select repository 드롭다운 목록에 소스 코드 저장소가 나타나요.

  5. 선택 사항. autotests 를 활성화해요.

  6. 기본 Build Rules 를 검토해요. 빌드 규칙은 Docker Hub가 소스 코드 저장소의 내용에서 무엇을 이미지로 빌드하는지, 그리고 그 결과 이미지가 Docker 저장소에서 어떻게 태그되는지를 제어해요. 편집하거나 삭제할 수 있는 기본 빌드 규칙이 설정돼 있는데, 이 기본 규칙은 소스 코드 저장소의 master 또는 main 브랜치에서 빌드하고 latest 태그로 Docker 이미지를 만들어요. 자세한 내용은 빌드 규칙 설정 을 확인해요.

  7. 선택 사항. 더 많은 빌드 규칙 을 추가하고 구성하려면 더하기 아이콘을 선택해요.

  8. 각 브랜치나 태그에 대해 Autobuild 토글을 활성화하거나 비활성화해요. autobuild가 활성화된 브랜치나 태그만 빌드되고 테스트되며, 결과 이미지가 저장소로 푸시돼요. autobuild가 비활성화된 브랜치는 테스트 목적으로 빌드되지만(저장소 레벨에서 활성화된 경우), 만들어진 Docker 이미지는 저장소로 푸시되지 않아요.

  9. 각 브랜치나 태그에 대해 Build Caching 토글을 활성화하거나 비활성화해요. 대용량 이미지를 자주 빌드하거나 종속성이 많다면 빌드 캐싱이 시간을 절약해줄 수 있어요. 모든 종속성이 빌드 시점에 해결되도록 하려면, 또는 로컬에서 더 빠르게 빌드되는 큰 레이어가 있다면 빌드 캐싱을 비활성화해 두세요.

  10. 설정을 저장하려면 Save 를 선택하고, 저장하고 초기 테스트를 실행하려면 Save and build 를 선택해요.

참고: 푸시할 때마다 Docker Hub에 알리도록 소스 코드 저장소에 웹훅이 자동으로 추가돼요. 하나 이상의 태그의 소스로 나열된 브랜치에 대한 푸시만 빌드를 트리거해요.

빌드 규칙 설정하기

기본적으로 자동 빌드를 설정하면 기본 빌드 규칙이 만들어져요. 이 기본 규칙은 소스 코드 저장소의 master 또는 main 브랜치의 변경 사항을 감시하고, master 또는 main 브랜치를 latest 태그가 붙은 Docker 이미지로 빌드해요.

Build Rules 섹션에서 빌드할 소스를 하나 이상 입력해요. 각 소스에 대해:

  1. 태그(tag) 또는 브랜치(branch) 중 무엇을 빌드할지 Source type 을 선택해요. 이는 빌드 시스템이 소스 코드 저장소에서 무엇을 찾아야 하는지 알려줘요.
  2. 빌드하려는 Source branch 또는 tag 의 이름을 입력해요. 자동 빌드를 처음 구성할 때 기본 빌드 규칙이 설정되는데, 이 기본 규칙은 소스 코드의 master 브랜치에서 빌드하고 latest 태그로 Docker 이미지를 만들어요. 정규식을 사용해 빌드할 소스 브랜치나 태그를 선택할 수도 있어요. 자세한 내용은 regexes 를 참고해요.
  3. 이 소스에서 빌드한 Docker 이미지에 적용할 tag 를 입력해요. 소스 선택에 정규식을 구성했다면 캡처 그룹을 참조하고 그 결과를 태그의 일부로 사용할 수 있어요. 자세한 내용은 regexes 를 참고해요.
  4. Dockerfile 위치를 소스 코드 저장소의 루트에 대한 상대 경로로 지정해요. Dockerfile이 저장소 루트에 있다면 이 경로를 /로 남겨 두세요.

참고: Docker Hub가 소스 코드 저장소에서 브랜치를 가져올 때 shallow clone을 수행해요 — 지정된 브랜치의 최신 커밋(tip)만 클론해요. 자세한 내용은 자동 빌드·자동 테스트 고급 옵션 을 참고해요.

빌드용 환경 변수

자동 빌드를 구성할 때 빌드 과정에서 사용하는 환경 변수의 값을 설정할 수 있어요. Build environment variables 섹션 옆의 더하기 아이콘을 선택하고 변수 이름과 값을 입력해 빌드 환경 변수를 추가해요. Docker Hub UI에서 변수 값을 설정하면 hooks 파일의 명령에서 이 변수들을 사용할 수 있어요. 그러나 이 값들은 Docker Hub 저장소에 admin 접근 권한이 있는 사용자만 볼 수 있도록 저장돼요. 따라서 액세스 토큰이나 비밀로 유지해야 하는 정보를 저장하는 데 사용할 수 있어요.

참고: 빌드 구성 화면에서 설정된 변수는 빌드 과정에서만 사용돼요. 서비스 링크를 만들 때처럼 서비스가 사용하는 환경 값과 혼동하면 안 돼요.

자동 빌드 고급 옵션

자동 빌드를 설정하려면 최소한 소스 브랜치 또는 태그와 대상 Docker 태그로 구성된 빌드 규칙이 필요해요. 다음도 할 수 있어요:

  • 빌드가 Dockerfile을 찾는 위치 변경
  • 빌드가 사용해야 할 파일 경로(빌드 컨텍스트) 설정
  • 빌드할 정적 태그 또는 브랜치 여러 개 설정
  • 정규식(regexes)을 사용해 빌드할 소스 코드를 동적으로 선택하고 동적 태그 생성

이 모든 옵션은 각 저장소의 Build configuration 화면에서 사용할 수 있어요.

  1. Docker Hub 에서 My Hub > Repositories 를 선택하고 편집하려는 저장소 이름을 선택해요.
  2. Builds 탭을 선택한 다음 Configure Automated builds 를 선택해요.

태그·브랜치 빌드

특정 브랜치나 태그에 대한 푸시가 빌드를 트리거하도록 자동 빌드를 구성할 수 있어요.

  1. Build Rules 섹션에서 더하기 아이콘을 선택해 빌드할 소스를 더 추가해요.

  2. 태그(tag) 또는 브랜치(branch) 중 무엇을 빌드할지 Source type 을 선택해요.

    참고: 이는 빌드 시스템에 코드 저장소에서 어떤 유형의 소스를 찾을지 알려줘요.

  3. 빌드하려는 Source branch 또는 tag 의 이름을 입력해요.

    참고: 이름을 입력하거나 정규식을 사용해 빌드할 소스 브랜치나 태그 이름을 매칭할 수 있어요. 자세한 내용은 regexes 를 참고해요.

  4. 이 소스에서 빌드한 Docker 이미지에 적용할 tag 를 입력해요.

    참고: 소스 선택에 정규식을 구성했다면 캡처 그룹을 참조하고 그 결과를 태그의 일부로 사용할 수 있어요. 자세한 내용은 regexes 를 참고해요.

  5. 설정하는 각 새 빌드 규칙에 대해 2~4단계를 반복해요.

빌드 컨텍스트와 Dockerfile 위치 설정

소스 코드 저장소의 파일 배치에 따라 이미지 빌드에 필요한 파일이 저장소 루트에 없을 수 있어요. 그렇다면 빌드가 파일을 찾는 경로를 지정할 수 있어요. 빌드 컨텍스트는 저장소 루트에 대한 상대 경로로, 빌드에 필요한 파일의 경로예요. Build context 필드에 이 파일들의 경로를 입력해요. 소스 코드 저장소의 루트를 빌드 컨텍스트로 설정하려면 /를 입력해요.

참고: Build context 필드에서 기본 경로 /를 삭제하고 비워 두면 빌드 시스템이 Dockerfile 경로를 빌드 컨텍스트로 사용해요. 하지만 혼동을 피하기 위해 완전한 경로를 지정하는 것이 좋아요.

Dockerfile 위치를 빌드 컨텍스트에 대한 상대 경로로 지정할 수 있어요. Dockerfile이 빌드 컨텍스트 경로의 루트에 있다면 Dockerfile 경로를 /로 남겨 두세요. Build context 필드가 비어 있다면 소스 저장소의 루트에서 Dockerfile 경로를 설정해요.

정규식과 자동 빌드

일치하는 브랜치나 태그만 빌드되도록 정규식(regex)을 지정할 수 있어요. 정규식의 결과를 사용해 빌드된 이미지에 적용되는 Docker 태그를 만들 수도 있어요. 괄호로 묶인 캡처 그룹을 최대 9개까지 사용해 빌드할 소스를 선택하고, Docker Tag 필드에서 {\1}부터 {\9}까지로 참조할 수 있어요.

BuildKit으로 이미지 빌드

Autobuilds는 기본적으로 BuildKit 빌드 시스템을 사용해요. 기존의 레거시 Docker 빌드 시스템을 사용하려면 환경 변수 DOCKER_BUILDKIT=0을 추가해요. BuildKit에 대한 자세한 내용은 BuildKit 페이지 를 참고해요.

팀용 Autobuild

자신의 사용자 계정에 자동 빌드 저장소를 만들면 빌드를 시작, 취소, 재시도할 수 있고 자신의 저장소를 편집·삭제할 수 있어요. 이와 같은 작업은 Docker Hub의 팀 저장소에서도 소유자라면 사용할 수 있어요. 쓰기 권한이 있는 팀의 구성원이라면 팀 저장소에서 빌드를 시작, 취소, 재시도할 수 있지만, 팀 저장소 설정을 편집하거나 팀 저장소를 삭제할 수는 없어요. 사용자 계정에 읽기 권한이 있거나 읽기 권한이 있는 팀의 구성원이라면 테스트 설정을 포함한 빌드 구성을 볼 수 있어요.

동작/권한 Read Write Admin Owner
빌드 세부 정보 보기 x x x x
시작, 취소, 재시도 x x x
빌드 설정 편집 x x
빌드 삭제 x

팀 autobuild용 서비스 사용자

참고: 팀에 대한 자동 빌드는 소유자만 설정할 수 있어요.

팀에 대한 자동 빌드를 설정하면 특정 사용자 계정에 연결된 OAuth를 사용해 Docker Hub에 소스 코드 저장소 접근 권한을 부여하게 돼요. 즉 Docker Hub는 연결된 소스 제공자 계정이 접근할 수 있는 모든 것에 접근할 수 있게 돼요. 조직과 팀의 경우 소스 제공자에 접근 권한을 부여할 전용 서비스 계정(service account)을 만드는 것이 좋아요. 이렇게 하면 개별 사용자의 접근 권한이 바뀌어도 빌드가 깨지지 않고, 개인 사용자의 개인 프로젝트가 전체 조직에 노출되지 않아요.

이 서비스 계정은 빌드할 모든 저장소에 접근할 수 있어야 하고, 배포 키를 관리할 수 있도록 소스 코드 저장소에 대한 관리 접근 권한이 있어야 해요. 필요하다면 특정 빌드에 필요한 저장소 집합으로만 이 계정을 제한할 수 있어요. 연결된 비공개 하위 모듈(비공개 종속성)이 있는 저장소를 빌드한다면, 해당 계정과 연결된 자동 빌드에 SSH_PRIVATE 환경 변수 오버라이드도 추가해야 해요. 자세한 내용은 Troubleshoot 를 참고해요.

  1. 소스 제공자에 서비스 사용자 계정을 만들고 그 계정용 SSH 키를 생성해요.

  2. 조직에 "build" 팀을 만들어요.

  3. 새 "build" 팀이 빌드해야 하는 각 저장소와 하위 모듈에 접근할 수 있는지 확인해요.

  4. GitHub나 Bitbucket에서 저장소의 Settings 페이지로 이동해요.

  5. 새 "build" 팀을 승인된 사용자 목록에 추가해요.

    • GitHub: Collaborators and Teams 에서 팀을 추가해요.
    • Bitbucket: Access management 에서 팀을 추가해요.

  6. 소스 제공자의 "build" 팀에 서비스 사용자를 추가해요.

  7. 소유자로 Docker Hub에 로그인하고 조직으로 전환한 다음, 서비스 계정을 사용해 소스 코드 저장소에 연결하는 지침을 따르세요.

    참고: 서비스 계정에 대한 연결을 만들려면 소스 코드 제공자의 개인 계정에서 로그아웃해야 할 수도 있어요.

  8. 선택 사항. 서비스 계정과 이전 지침 을 사용해, 생성한 SSH 키로 비공개 하위 모듈이 있는 빌드를 설정해요.

다음 단계 (What's Next?)

  • 환경 변수, 훅 등으로 빌드 과정 커스터마이즈
  • 자동 테스트 추가
  • 빌드 관리
  • 문제 해결 (Troubleshoot)

더 알아보기 (Learn more)