Docker 이미지를 운영 환경에 배포할 때 매번 직접 빌드하고 Push하는 방식은 시간이 많이 걸리고 관리가 어렵습니다.

예:

코드 변경

↓

수동 Docker Build 실행

↓

이미지 생성

↓

Registry Push

↓

서버 배포

프로젝트 규모가 커질수록 이러한 반복 작업은 비효율적입니다.

이러한 문제를 해결하기 위해 많은 개발 환경에서는 CI/CD 자동화를 사용합니다.

GitHub Actions와 Docker Buildx Bake를 함께 사용하면 코드가 변경될 때마다 자동으로 Docker 이미지를 빌드하고 Registry에 Push할 수 있습니다.

예:

name: Docker Build

on:
  push:
    branches:
      - main

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - run: docker buildx bake --push

코드가 Push되면 자동으로 Docker 이미지가 생성됩니다.

이번 글에서는 Docker Buildx Bake와 GitHub Actions 연동 방법, Buildx 설정, Cache 적용, Registry Push, Multi-platform 빌드 자동화까지 자세히 알아보겠습니다.

Docker Buildx Bake GitHub Actions란 무엇인가?

Docker Buildx Bake GitHub Actions는 GitHub Actions 환경에서 Docker Buildx Bake를 자동 실행하는 CI/CD 구성 방법입니다.

기본 구조:

Git Push

↓

GitHub Actions 실행

↓

Docker Buildx Bake 실행

↓

Docker Image 생성

↓

Registry Push

자동화된 Docker 이미지 빌드 환경을 만들 수 있습니다.

Docker Buildx Bake와 GitHub Actions를 사용하는 이유

수동 빌드 방식:

docker buildx bake --push

문제:

• 직접 실행 필요
• 빌드 환경 차이 발생
• 배포 과정 반복
• 실수 가능성 증가

GitHub Actions 사용:

코드 변경

↓

자동 Build

↓

자동 Push

↓

자동 배포

장점:

• 반복 작업 제거
• 동일한 빌드 환경 유지
• 빠른 배포 가능
• CI/CD 자동화

GitHub Actions 기본 Docker Buildx 설정

Workflow 파일 위치:

.github/

└── workflows/

    └── docker-build.yml

기본 설정:

name: Docker Build

on:

  push:

    branches:

      - main


jobs:

  docker:

    runs-on: ubuntu-latest

    steps:

      - name: Checkout

        uses: actions/checkout@v4


      - name: Setup Buildx

        uses: docker/setup-buildx-action@v3

Buildx 환경을 준비합니다.

Docker Buildx Bake 실행하기

GitHub Actions:

- name: Build Image

  run: |

    docker buildx bake

동작:

docker-bake.hcl 확인

↓

Target 확인

↓

Image Build

기본 Bake 파일을 자동으로 사용합니다.

Docker Buildx Bake Registry Push 설정

운영 환경에서는 이미지를 Registry에 저장해야 합니다.

예:

Docker Hub Login:

- name: Login Docker Hub

  uses: docker/login-action@v3

  with:

    username: ${{ secrets.DOCKER_USERNAME }}

    password: ${{ secrets.DOCKER_PASSWORD }}

Build Push:

- name: Build and Push

  run: |

    docker buildx bake --push

결과:

GitHub Actions

↓

Docker Build

↓

Docker Hub Push

Docker Buildx Bake GitHub Actions Cache 설정

CI 환경에서는 Cache 사용이 중요합니다.

설정:

docker-bake.hcl

target "app" {

  cache-from = [

    "type=gha"

  ]


  cache-to = [

    "type=gha"

  ]

}

GitHub Actions Cache를 활용합니다.

효과:

• 반복 빌드 속도 향상
• Runner 초기화 문제 감소
• CI 비용 절감

Docker Buildx Bake Multi-platform 빌드 자동화

여러 서버 환경을 지원하려면 Multi-platform 빌드가 필요합니다.

docker-bake.hcl:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

GitHub Actions:

- name: Build Multi Platform

  run: |

    docker buildx bake --push

결과:

linux/amd64 이미지

+

linux/arm64 이미지

하나의 Image Tag로 여러 환경을 지원할 수 있습니다.

Docker Buildx Bake Secret과 GitHub Actions 활용

Private Repository나 API Key가 필요한 경우 Secret을 사용할 수 있습니다.

GitHub Secret:

API_KEY

SSH_KEY

TOKEN

Workflow:

env:

  API_KEY: ${{ secrets.API_KEY }}

Bake:

target "app" {

  secret = [

    "id=api,env=API_KEY"

  ]

}

민감한 정보를 안전하게 전달할 수 있습니다.

Docker Buildx Bake Matrix와 GitHub Actions 활용

여러 환경을 자동 테스트할 수 있습니다.

예:

docker-bake.hcl

target "test" {

  matrix = {

    version = [

      "18",

      "20",

      "22"

    ]

  }

}

GitHub Actions 실행:

- name: Run Matrix Build

  run: |

    docker buildx bake test

여러 버전을 자동으로 테스트할 수 있습니다.

Docker Buildx Bake GitHub Actions 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── .github/

    └── workflows/

        └── docker.yml

docker.yml:

name: Docker Build


on:

  push:

    branches:

      - main


jobs:

  build:

    runs-on: ubuntu-latest


    steps:

      - name: Checkout

        uses: actions/checkout@v4


      - name: Setup Buildx

        uses: docker/setup-buildx-action@v3


      - name: Login Registry

        uses: docker/login-action@v3


      - name: Build

        run: |

          docker buildx bake --push

코드 Push만으로 Docker 이미지가 자동 생성됩니다.

Docker Buildx Bake GitHub Actions와 배포 자동화

전체 흐름:

개발자가 코드 Push

↓

GitHub Actions 실행

↓

Docker Buildx Bake 실행

↓

Registry Push

↓

서버 Pull

↓

서비스 업데이트

활용:

• Kubernetes 배포
• Docker Compose 배포
• Cloud 서버 운영

Linux 서버 문제 해결

기존에는 코드를 수정할 때마다 직접 서버에서 Docker Build를 실행했습니다.

기존:

docker buildx bake --push

문제:

• 반복 작업 발생
• 빌드 환경 차이
• 배포 시간 증가

GitHub Actions 적용:

- name: Build

  run: |

    docker buildx bake --push

결과:

• 코드 Push 자동 Build
• 자동 Image Push
• 동일한 환경에서 빌드

배포 과정을 자동화할 수 있었습니다.

Docker Buildx Bake GitHub Actions 사용 시 주의사항

첫 번째는 Registry 인증 정보를 GitHub Secret으로 관리해야 합니다.

두 번째는 Cache 설정을 함께 사용하는 것이 좋습니다.

세 번째는 운영 Branch와 개발 Branch Workflow를 분리하는 것이 좋습니다.

네 번째는 Build 결과와 로그를 확인하는 과정이 필요합니다.

Best Practice

Docker Buildx Bake GitHub Actions 활용 방법:

• docker-bake.hcl 중앙 관리
• GitHub Secret 사용
• Buildx Cache 적용
• Registry Push 자동화
• Multi-platform 빌드 활용
• Production Workflow 분리

자주 묻는 질문

Docker Buildx Bake를 GitHub Actions에서 사용할 수 있나요?

가능합니다.

Workflow 파일에서 Docker Buildx Bake 명령을 실행하면 됩니다.

Docker 이미지 Push도 자동화할 수 있나요?

가능합니다.

Registry Login 후 --push 옵션을 사용하면 됩니다.

Cache를 사용할 수 있나요?

가능합니다.

GitHub Actions Cache(type=gha)를 활용할 수 있습니다.

여러 플랫폼 이미지를 만들 수 있나요?

가능합니다.

linux/amd64와 linux/arm64 Multi-platform 빌드를 자동화할 수 있습니다.

마무리

Docker Buildx Bake와 GitHub Actions를 함께 사용하면 Docker 이미지 빌드와 배포 과정을 완전히 자동화할 수 있습니다.

코드 변경부터 이미지 생성, Registry Push까지 자동으로 처리할 수 있어 반복적인 작업을 줄이고 안정적인 CI/CD 환경을 구축할 수 있습니다.

특히 여러 서비스와 여러 플랫폼을 운영하는 프로젝트에서는 Docker Buildx Bake, Cache, Secret, Matrix 기능을 GitHub Actions와 함께 활용하면 효율적인 자동화 시스템을 만들 수 있습니다.