Autobuilds에서 마이그레이션하기

Autobuilds에서 마이그레이션하기 (Migrate from Autobuilds)

Docker Hub Autobuilds 설정을 GitHub Actions와 Bitbucket Pipelines 같은 지속적 통합(CI) 워크플로우로 옮기는 방법을 단계별로 배워볼게요.

출처: 문서

본문

경고: Docker Hub Automated Builds는 더 이상 사용되지 않는(deprecated) 기능이에요. 2027년 4월 1일에 완전히 퇴역할 예정이에요.

이 가이드는 Autobuilds가 지원하는 두 버전 관리 서비스의 내장 CI 서비스인 GitHub Actions와 Bitbucket Pipelines에 초점을 맞춰, Docker Hub Autobuilds 설정을 지속적 통합(CI) 워크플로우로 마이그레이션하는 방법을 설명해요.

1단계: 액세스 토큰 만들기

CI 워크플로우가 Docker Hub에서 이미지를 풀하고 푸시할 수 있게 하려면 먼저 액세스 토큰을 만들어야 해요.

  • 개인 저장소의 경우: Read & Write 권한이 있는 Personal Access Token을 만들어요.
  • 조직 저장소의 경우: 다음 권한을 가진 Organization Access Token을 만들어요.
    • Read public repositories
    • 빌드가 풀해야 하는 비공개 저장소에 대한 Image Pull
    • 빌드된 이미지가 푸시될 저장소에 대한 Image Push

계정 네임스페이스 아래의 모든 관련 Docker Hub 저장소에 충분한 권한이 있다면, 같은 토큰을 그 네임스페이스의 모든 CI 워크플로우에 사용할 수 있어요. 토큰은 암호 관리자나 CI/CD 플랫폼의 시크릿 관리자에 안전하게 저장해요. 토큰을 소스 코드 저장소에 커밋하는 일은 절대 하지 마세요.

2단계: Autobuilds 구성 추출하기

현재 Autobuilds를 사용하도록 구성된 각 Docker Hub 저장소에 대해, 기존 기능을 복제하도록 CI 워크플로우를 설정하기 위해 그 구성을 추출해야 해요. 구성을 추출하는 유일한 방법은 Docker Hub 웹 인터페이스를 통하는 것이에요.

  1. Docker Hub 에 로그인해요.
  2. My Hub > Your namespace > Repositories > Your Repository 로 이동해 저장소로 이동해요.
  3. Builds 탭으로 가서 Configure automated builds 를 선택해요. 기존 빌드 구성이 없다면 이 저장소는 Autobuilds용으로 구성되지 않은 것이에요.
  4. 다음 구성 세부 사항을 기록해요:
    • Source Repository: GitHub 또는 Bitbucket 저장소. 조직은 네임스페이스이고 저장소는 저장소 이름이에요. 여기에 워크플로우를 추가해야 해요.
    • Autotest: Pull Requests에 대해 Autotest가 활성화되어 있다면(내부 전용 또는 내부·외부 모두), 워크플로우에서 Autotest 단계를 실행하기 위해 추가 단계가 필요해요.
    • Repository Links: 지원되지 않으므로 무시해요. 체인 빌드가 필요하다면 CI 서비스 문서에서 빌드를 함께 체인하는 방법을 확인해요.
    • Build Rules: 빌드의 트리거, 태그, 경로를 지정해요. Autobuild가 꺼져 있는 항목은 무시해요.
    • Build Environment Variables: 빌드에 환경 변수로 주입되는 사용자 정의 변수. 이것들을 워크플로우에 추가해야 해요. 환경 변수에 시크릿이 포함되어 있다면 CI 서비스의 시크릿 관리자에 추가해요. 그런 다음 CI 플랫폼 문법을 사용해 이 시크릿을 참조하도록 Dockerfile이나 빌드 스크립트를 업데이트해요. 시크릿 처리 방법은 CI 서비스 문서를 확인해요.

구성 예시

다음 이미지는 Autobuilds 구성의 예시를 보여줘요. 그림에 표시된 예시를 바탕으로 이 Autobuilds 구성에 대해 다음 항목을 기록하게 돼요:

  • 소스 코드 저장소: GitHub 저장소 docker/docker-rust-hello
  • Autotest: 비활성화
  • 빌드 규칙 1: main 브랜치에 새 커밋이 감지되면 latest 태그로 이미지를 빌드하고 푸시해요. Dockerfile은 ./Dockerfile에 있고 빌드 컨텍스트는 클론된 코드의 루트예요.
  • 빌드 규칙 2: 정규식 ^v([0-9.]+)$와 일치하는 태그에 새 커밋이 감지되면 v{\1} 태그로 이미지를 빌드하고 푸시해요. Dockerfile은 ./Dockerfile에 있고 빌드 컨텍스트는 클론된 코드의 루트예요.
  • 환경 변수: 키 ENV_KEY, 값 ENV_VALUE

3단계: CI/CD 플랫폼으로 마이그레이션하기

소스 코드 저장소 호스팅 플랫폼과 일치하는 탭을 선택해요.

GitHub Actions

소스 코드 저장소가 GitHub에 호스팅되어 있다면 Docker Autobuilds 예시 저장소 를 확인해요. .github/workflows 디렉터리 아래의 파일을 제외한 모든 파일은 예시 전용이에요. 저장소의 readme에는 제공된 두 워크플로우 중 하나를 사용해 Autobuilds에서 GitHub Actions로 마이그레이션하는 방법이 자세히 설명돼 있어요:

  • simple-build 워크플로우는 Docker 이미지를 빌드해 Docker Hub 저장소에 푸시해요.
  • full-autobuilds 워크플로우는 빌드, 태깅, Docker Compose 테스트 실행, 선택적 bash 훅 파일 실행을 포함해 Autobuilds 실행에서 흔히 사용되는 모든 단계를 포함해요.

마이그레이션 단계:

  1. 예시 저장소 readme의 지침에 따라 GitHub 저장소에 CI GitHub Action 워크플로우를 구성해요. 워크플로우에는 각 단계의 역할과 변경해야 할 위치에 대한 주석이 포함돼 있어요.
  2. 해야 할 중요한 변경 사항:
    • DOCKER_REPOSITORY_NAME 환경 변수를 Docker Hub 저장소의 전체 이름으로 설정해요
    • 이미지 태깅 정책을 설정해요
    • 워크플로우 트리거를 설정해요
  3. 관련 문서 링크는 readme와 워크플로우 주석에 제공돼요.
  4. GitHub Actions로 마이그레이션을 완료한 후, Docker Hub 저장소에서 빌드 구성을 삭제해요:
    • 저장소의 Builds 탭으로 이동해요.
    • Configure automated builds 를 선택해요.
    • Delete Build Configuration 을 선택해요.

Bitbucket Pipelines

소스 코드 저장소가 Bitbucket에 호스팅되어 있다면 Docker Autobuilds Bitbucket 예시 저장소 를 확인해요. bitbucket-pipelines.yml 파일을 제외한 모든 파일은 예시 전용이에요. 저장소의 readme에는 제공된 예시 bitbucket-pipelines.yml 구성 파일을 사용해 Autobuilds에서 Bitbucket Pipelines로 마이그레이션하는 방법이 자세히 설명돼 있어요.

파이프라인 예시에는 세 개의 개별 파이프라인이 포함돼 있어요:

  • branches/main: 특정 브랜치 변경 시 이미지를 빌드, 테스트, 푸시하는 방법을 보여줘요
  • tags/*: 태그 푸시 시 이미지를 빌드, 테스트, 푸시하는 방법을 보여주고, Git 태그와 동일하게 이미지에 태그를 붙여요
  • pull-requests/*: 풀 리퀘스트에서 이미지를 빌드·테스트하되 푸시하지 않는 방법을 보여줘요

마이그레이션 단계:

  1. 예시 저장소 readme의 지침에 따라 Bitbucket 저장소에 Bitbucket Pipeline을 구성해요. 파이프라인 구성의 주석은 각 부분의 역할과 변경해야 할 위치를 설명해요.
  2. 해야 할 중요한 변경 사항:
    • DOCKER_REPOSITORY_NAME 환경 변수를 Docker Hub 저장소의 전체 이름으로 설정해요
    • 이미지 태깅 정책을 설정해요 (각 파이프라인에서 DOCKER_TAG 변수가 설정된 위치 확인)
    • 브랜치, 태그 및/또는 풀 리퀘스트에 대한 파이프라인 트리거를 설정해요
  3. 관련 문서 링크는 readme와 워크플로우 주석에 제공돼요.
  4. Bitbucket Pipelines로 마이그레이션을 완료한 후, Docker Hub 저장소에서 Build 구성 을 삭제해요:
    • 저장소의 Builds 탭으로 이동해요.
    • Configure automated builds 를 선택해요.
    • Delete Build Configuration 을 선택해요.

더 알아보기 (Learn more)