[Github Actions] Docker 이미지 빌드·푸시 자동화와 Mac에서 실행하기

태그와 릴리즈 생성 다음에는 Docker 이미지를 빌드하고 GHCR에 올리는 작업을 연결했다.

직접 입력했던 빌드·푸시 명령을 워크플로로 옮기면서, Job 간 의존 관계와 결과 전달 방식을 배웠다.

Job 사이의 순서 정하기

buildImageAndPush:
  name: 도커 이미지 빌드와 푸시
  needs: makeTagAndRelease
  runs-on: ubuntu-latest

 

needs는 앞 Job이 성공한 뒤 현재 Job을 실행하도록 연결한다.

 

태그·릴리즈 생성 성공
          ↓
이미지 빌드·푸시

 

앞 Job이 실패하면 기본적으로 뒤 Job은 실행되지 않고 건너뛰어진다.

반대로 이미지 빌드가 실패하더라도 이미 생성된 릴리즈가 자동으로 삭제되지는 않는다. 따라서 릴리즈가 보인다는 사실만으로 이미지 빌드·푸시까지 성공했다고 판단하면 안 된다.

다음 Job에서도 checkout이 필요한 이유

이미지 빌드 Job에서도 코드를 가져온다.

steps:
  - uses: actions/checkout@v4

 

GitHub 제공 러너를 사용하는 이번 구성에서는 Job마다 별도 실행 환경이 준비된다. 앞 Job에서 가져온 파일을 다음 Job이 자동으로 공유하지 않는다.

needs는 실행 순서를 연결하지만 파일까지 전달하지는 않는다.

GHCR에 로그인하기

GHCR은 GitHub Container Registry로, 빌드한 컨테이너 이미지를 보관하는 곳이다.

- name: Docker Buildx 설치
  uses: docker/setup-buildx-action@v2

- name: 레지스트리 로그인
  uses: docker/login-action@v2
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

 

이미지를 빌드하는 것과 레지스트리에 올리는 것은 다르다.

 

빌드 → 이미지 생성
푸시 → 레지스트리에 업로드
풀   → 다른 환경에서 이미지 다운로드

 

러너에서 빌드만 하고 푸시하지 않았다면 운영 서버가 GHCR에서 그 결과를 내려받을 수 없다.

버전 태그와 latest 함께 사용하기

- name: 빌드 앤 푸시
  uses: docker/build-push-action@v3
  with:
    context: .
    platforms: linux/amd64,linux/arm64
    push: true
    tags: |
      ghcr.io/${{ env.OWNER_LC }}/deploy:${{ needs.makeTagAndRelease.outputs.tag_name }}
      ghcr.io/${{ env.OWNER_LC }}/deploy:latest

 

context: .은 현재 작업 디렉터리를 빌드 컨텍스트로 사용하고, push: true는 빌드 결과를 레지스트리에 올리도록 설정한다.

이미지에는 생성한 버전 태그와 latest를 함께 붙였다.

 

deploy:v1.2.0
deploy:latest

 

Git 태그와 이미지 태그를 연결하면 어떤 버전의 코드로 만든 이미지인지 추적하기 쉽다.

다만 latest가 새 이미지를 가리켜도 실행 중인 컨테이너는 바뀌지 않는다. 새 버전을 사용하려면 이미지를 내려받고 새 컨테이너를 실행해야 한다.

Mac에서 이미지를 내려받지 못했던 문제

Mac에서 이미지를 내려받지 못해 다음 설정을 추가했다.

platforms: linux/amd64,linux/arm64

 

이를 적용해 다시 빌드·푸시한 뒤 이미지를 사용할 수 있었다.

이 설정은 러너를 Mac으로 바꾸는 것이 아니라, 만들 이미지의 대상 플랫폼을 지정하는 것이다.

 

설정	의미
runs-on	작업을 수행할 러너 환경
platforms	빌드한 이미지가 실행될 대상 환경

Ubuntu 러너에서도 ARM64용 이미지를 만들 수 있다. 빌드하는 환경과 결과물을 실행할 환경이 반드시 같아야 하는 것은 아니다.

멀티 플랫폼 이미지가 제공되면 Docker는 내려받는 환경에 맞는 버전을 선택한다. 

오류 메시지를 별도로 남기지는 않아 원인을 단정할 수는 없지만, 이번 경험을 통해 이미지의 CPU 아키텍처도 확인해야 한다는 것을 배웠다.

이미지 내려받기와 권한

비공개 이미지를 내려받는 환경에서는 인증이 필요하다. 내려받기만 한다면 read:packages처럼 목적에 맞는 읽기 권한을 사용한다.

불필요한 쓰기·삭제 권한까지 주지 않으면 토큰이 노출됐을 때 가능한 피해를 줄일 수 있다.

토큰 값은 생성 직후 안전하게 보관해야 한다. 페이지를 나간 뒤에는 기존 값을 다시 확인할 수 없으므로, 코드나 Git 저장소에 복사해두는 방식은 피해야 한다.

컨테이너 실행 확인하기

docker run --rm -d \
  --name deploy_1 \
  -p 8021:80 \
  ghcr.io/사용자/deploy:latest

 

이미지 경로의 사용자는 자신의 GHCR 소유자 이름으로 바꾼다.

브라우저에서는 다음 주소로 접속한다.

 

http://localhost:8021

 

호스트의 8021번 포트로 들어온 요청이 컨테이너의 80번 포트로 전달된다. Hello World가 보이면 가져온 이미지가 내 컴퓨터에서 실행되고 웹 요청을 처리하는 것까지 확인한 셈이다.

이번 자동화는 이미지를 만들고 공유하는 과정까지 연결한다. 운영 서버의 기존 컨테이너를 교체하는 배포는 별도의 작업이라는 점도 구분해야 한다.