GitHub Actions용 Dockerfile 지원

GitHub Actions용 Dockerfile 지원

Docker 컨테이너 액션용 Dockerfile을 만들 때 일부 Docker 지침이 GitHub Actions와 액션의 메타데이터 파일과 어떻게 상호 작용하는지 알아둬야 해요.

출처: 문서

본문

Docker 컨테이너 액션용 Dockerfile을 만들 때 일부 Docker 지침이 GitHub Actions 및 액션의 메타데이터 파일과 어떻게 상호 작용하는지 알아야 합니다.

USER

Docker 액션은 기본 Docker 사용자(root)로 실행되어야 합니다. GITHUB_WORKSPACE 디렉터리에 접근하지 못하게 되므로 Dockerfile에서 USER 지침을 사용하지 마세요. 자세한 내용은 Variables reference와 Docker 문서의 USER reference를 참고하세요.

FROM

Dockerfile의 첫 번째 지침은 Docker 베이스 이미지를 선택하는 FROM이어야 합니다. 자세한 내용은 Docker 문서의 FROM reference를 참고하세요.

FROM 인수를 설정할 때의 몇 가지 모범 사례는 다음과 같습니다:

  • 공식 Docker 이미지를 사용하는 것이 좋습니다. 예를 들어 python이나 ruby.
  • 버전 태그가 있다면 사용하세요. 가능하면 메이저 버전을 사용하세요. 예를 들어 node:latest 대신 node:10을 사용하세요.
  • Debian 운영 체제를 기반으로 하는 Docker 이미지를 사용하는 것이 좋습니다.

WORKDIR

GitHub는 작업 디렉터리 경로를 GITHUB_WORKSPACE 환경 변수에 설정합니다. Dockerfile에서 WORKDIR 지침을 사용하지 않는 것이 좋습니다. 액션이 실행되기 전에 GitHub는 Docker 이미지에서 해당 위치에 있던 모든 것 위에 GITHUB_WORKSPACE 디렉터리를 마운트하고 GITHUB_WORKSPACE를 작업 디렉터리로 설정합니다. 자세한 내용은 Variables reference와 Docker 문서의 WORKDIR reference를 참고하세요.

ENTRYPOINT

액션의 메타데이터 파일에 entrypoint를 정의하면 Dockerfile에 정의된 ENTRYPOINT를 재정의합니다. 자세한 내용은 Metadata syntax reference를 참고하세요.

Docker ENTRYPOINT 지침에는 shell 형식과 exec 형식이 있습니다. Docker ENTRYPOINT 문서는 ENTRYPOINT 지침의 exec 형식을 사용할 것을 권장합니다. exec 및 shell 형식에 대한 자세한 내용은 Docker 문서의 ENTRYPOINT reference를 참고하세요.

Dockerfile에서 엔트리포인트를 지정하는 데 WORKDIR을 사용하면 안 됩니다. 대신 절대 경로를 사용해야 합니다. 자세한 내용은 WORKDIR을 참고하세요.

컨테이너가 ENTRYPOINT 지침의 exec 형식을 사용하도록 구성하면 액션의 메타데이터 파일에 구성된 args는 명령 셸에서 실행되지 않습니다. 액션의 args에 환경 변수가 포함되어 있으면 변수가 대체되지 않습니다. 예를 들어 다음 exec 형식을 사용하면 $GITHUB_SHA에 저장된 값을 출력하지 않고 "$GITHUB_SHA"를 출력합니다.

ENTRYPOINT ["echo $GITHUB_SHA"]

변수 대체를 원한다면 shell 형식을 사용하거나 셸을 직접 실행하세요. 예를 들어 다음 exec 형식을 사용해서 셸을 실행해 GITHUB_SHA 환경 변수에 저장된 값을 출력할 수 있습니다.

ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"]

ENTRYPOINT에서 exec 형식을 사용하는 Docker 컨테이너에 액션의 메타데이터 파일에 정의된 args를 공급하려면 ENTRYPOINT 지침에서 호출하는 entrypoint.sh라는 셸 스크립트를 만드는 것을 권장합니다:

예시 Dockerfile

# Container image that runs your code
FROM debian:9.5-slim

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT ["/entrypoint.sh"]

예시 entrypoint.sh 파일

위 예시 Dockerfile을 사용하면 GitHub가 액션의 메타데이터 파일에 구성된 args를 entrypoint.sh에 인수로 보냅니다. entrypoint.sh 파일 맨 위에 #!/bin/sh shebang을 추가해서 시스템의 POSIX 호환 셸을 명시적으로 사용하세요.

#!/bin/sh

# `$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf " '%s'" "$@"
printf '\n'

코드는 실행 가능해야 합니다. 워크플로에서 사용하기 전에 entrypoint.sh 파일에 execute 권한이 있는지 확인하세요. 터미널에서 다음 명령으로 권한을 수정할 수 있습니다:

chmod +x entrypoint.sh

ENTRYPOINT 셸 스크립트가 실행 가능하지 않으면 다음과 비슷한 오류가 발생합니다:

Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown

CMD

액션의 메타데이터 파일에 args를 정의하면 args가 Dockerfile에 지정된 CMD 지침을 재정의합니다. 자세한 내용은 Metadata syntax reference를 참고하세요.

Dockerfile에서 CMD를 사용한다면 다음 지침을 따르세요:

  1. 필수 인수를 액션의 README에 문서화하고 CMD 지침에서는 생략하세요.
  2. args를 지정하지 않고도 액션을 사용할 수 있게 하는 기본값을 사용하세요.
  3. 액션이 --help 플래그나 이와 유사한 것을 노출한다면 그것을 사용해서 액션이 스스로 문서화하도록 하세요.

지원되는 Linux 기능(Capabilities)

GitHub Actions는 Docker가 지원하는 기본 Linux 기능을 지원합니다. 기능을 추가하거나 제거할 수 없습니다. Docker가 지원하는 기본 Linux 기능에 대한 자세한 내용은 Docker 문서의 Linux kernel capabilities를 참고하세요. Linux 기능에 대해 더 자세히 알아보려면 Linux man-pages의 Overview of Linux capabilities를 참고하세요.

더 알아보기 (Learn more)