docker-build-runner

Forgejo Actions에서 Docker daemon 없이 linux/amd64, linux/arm64 이미지를 빌드하고 Forgejo Packages container registry로 푸시하는 단일 workflow 예제입니다.

목표는 Dockerfile이 있는 프로젝트에 workflow YAML 하나만 추가해서 이미지 빌드와 패키지 관리를 자동화하는 것입니다. 이 저장소의 Dockerfile은 USER root로 패키지를 설치하고 다시 앱 유저로 돌아오는 workflow 테스트용 예시입니다.

사용법

대상 프로젝트에 이 저장소의 .forgejo/workflows/docker-publish.yml 파일을 그대로 복사해서 사용합니다.

기본 설정은 아래와 같습니다.

env:
  REGISTRY: git.jhan.me
  IMAGE_NAME: ${{ github.repository }}
  DOCKERFILE: Dockerfile
  CONTEXT: .
  PLATFORMS: linux/amd64,linux/arm64
  TOOL_ARCH: arm64

대부분의 프로젝트에서는 REGISTRY만 자신의 Forgejo registry 주소로 맞추면 됩니다. 패키지 이름을 repo 경로와 다르게 쓰려면 IMAGE_NAME을 직접 지정하세요. TOOL_ARCH는 kaniko/crane 실행 파일 아키텍처입니다. amd64 runner에서는 amd64, arm64 runner에서는 arm64를 사용하세요. runner가 정확히 native architecture를 보고한다면 auto로 둘 수 있습니다.

예시:

env:
  REGISTRY: git.jhan.me
  IMAGE_NAME: jeonghan-yee/my-app

Secrets

대상 프로젝트의 Forgejo repository secrets에 아래 값을 설정합니다.

• REGISTRY_USERNAME
• REGISTRY_PASSWORD

REGISTRY_USERNAME은 Forgejo 사용자명이고, REGISTRY_PASSWORD는 package write 권한이 있는 Forgejo access token을 권장합니다. workflow는 private repository의 source archive를 내려받을 때도 이 값을 Authorization: token ... 헤더로 먼저 사용하고, 실패하면 REGISTRY_USERNAME / REGISTRY_PASSWORD Basic auth로 다시 시도합니다.

태그

main 또는 master branch push:

• latest
• sha-<12자리 커밋 SHA>

v* git tag push:

• <git tag>
• sha-<12자리 커밋 SHA>

Runner 요구사항

workflow는 Docker CLI, Docker daemon, /var/run/docker.sock, docker buildx를 사용하지 않습니다. 대신 kaniko로 아키텍처별 이미지를 푸시하고, crane으로 멀티 아키텍처 manifest index를 만듭니다.

job은 공식 Kaniko debug 이미지 gcr.io/kaniko-project/executor:v1.24.0-debug 안에서 실행됩니다. 이 구조가 Dockerfile의 RUN, USER root, package manager 실행을 처리하는 데 필요합니다. workflow는 actions/checkout 대신 Forgejo archive URL로 대상 repo의 source를 내려받고, 실행 중에 아래 도구를 사용합니다.

• crane
• kaniko executor

아키텍처별 임시 태그도 생성됩니다.

• build-<12자리 커밋 SHA>-amd64
• build-<12자리 커밋 SHA>-arm64

최종 사용 태그는 latest, sha-<12자리 커밋 SHA>, git tag입니다.

Troubleshooting

아래 에러는 Buildah/Podman 계열이 runner 컨테이너 안에서 user namespace를 만들 수 없을 때 발생합니다.

Error during unshare(CLONE_NEWUSER): Operation not permitted

현재 workflow는 이 문제를 피하려고 Buildah 대신 kaniko와 crane을 사용합니다.

단, kaniko 자체가 다른 CPU 아키텍처의 Dockerfile RUN 명령을 자동으로 에뮬레이션하지는 않습니다. 현재 테스트 runner처럼 host에 binfmt/QEMU가 등록되어 있으면 non-native RUN도 처리할 수 있지만, 그렇지 않다면 아래 중 하나가 필요합니다.

• amd64, arm64 native runner를 각각 두고 플랫폼별로 빌드
• runner host에 binfmt/QEMU를 미리 등록
• privileged runner에서 Buildah/BuildKit 계열 builder 사용