[Docker][보안] private Git clone이 필요한 build에서 secret mount와 SSH mount를 언제 나누고 build log와 history에서 무엇을 확인하나

IT 리서치 노트

[Docker][보안] private Git clone이 필요한 build에서 secret mount와 SSH mount를 언제 나누고 build log와 history에서 무엇을 확인하나

Docker build에서 private Git clone이 끼면 많은 팀이 token 하나만 숨기면 끝난다고 생각한다. 하지만 2026년 8월 6일 기준 Docker 공식 문서를 다시 보면 build secret, SSH mount, remote Git context authentication은 서로 다른 경로다. 이 글은 private Git clone이 필요한 build에서 secret mount와 SSH mount를 언제 나누고, build log와 history에서 무엇을 확인해야 사고를 줄일 수 있는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 clone 주소가 SSH 기반이면 SSH mount를 먼저 보고, RUN 단계에서 토큰 파일이나 환경변수를 잠깐 읽어야 하면 secret mount를 먼저 보는 편이 짧다. remote Git context 자체가 private라면 Dockerfile 안 secret보다 builder fetch 단계 인증이 더 앞선다.

즉 private Git build 보안은 "비밀을 숨겼는가"보다 "어느 단계가 그 비밀을 소비했는가"를 먼저 나눠야 한다. context fetch, clone step, package install, final image 검사 네 단계가 각각 다른 로그를 남긴다.

2. 어디서 실제로 막히는가

실무에서 자주 꼬이는 지점은 세 가지다. 첫째, SSH clone인데도 HTTP token secret을 억지로 넣어 build command만 복잡해진다. 둘째, remote Git context가 private인데 Dockerfile 안 RUN secret만 바꾼다. 셋째, build는 성공했지만 build log나 history에 credential 흔적이 남았는지 마지막 검사를 생략한다.

Docker 문서는 build secrets와 SSH mounts를 별도로 두고, private remote Git context 인증도 별도 항목으로 설명한다. 이 구조 자체가 인증 경계를 나눠야 한다는 힌트다. builder가 context를 받는 단계와, Dockerfile instruction이 실행되는 단계는 같은 층이 아니다.

그래서 질문도 두 단계로 나뉜다. 지금 필요한 것이 private repository fetch인지, build step 안에서 외부 API나 package registry 토큰을 읽는 것인지다. 전자는 clone 경로와 remote context 인증이 중요하고, 후자는 secret mount 소비와 build log 출력이 중요하다.

• 증상: build는 되는데 어떤 인증 경로가 실제로 쓰였는지 설명이 안 된다.
• 실패: SSH clone과 token file install을 같은 secret 설계로 묶는다.
• 막힘: remote Git context 인증과 RUN 단계 secret 소비를 한 로그로만 본다.
• 누락: docker history와 build logs로 흔적을 닫지 않는다.

질문	먼저 볼 층	실무 판단
builder가 private 저장소를 못 가져온다	remote Git context auth	Dockerfile 안 secret보다 fetch 단계 인증을 먼저 본다
RUN 단계 package install이 인증 실패한다	secret mount 또는 SSH mount	clone 주소와 token 소비 방식에 따라 mount를 나눈다
build 뒤 흔적이 걱정된다	history / logs / image inspect	성공 여부와 별도로 흔적 검사를 남긴다

3. 실무에서 적용하는 순서

실무 순서는 다섯 단계가 가장 빠르다. 먼저 repository address가 SSH인지 HTTPS인지 적는다. 다음으로 인증이 remote context fetch에서 필요한지, RUN instruction 안에서 필요한지 분리한다. 세 번째로 SSH clone이면 SSH mount, token file install이면 secret mount로 바꾼다. 네 번째로 실행 중에도 필요한 값은 Dockerfile 밖 runtime secret으로 뺀다. 마지막으로 build logs와 docker history를 같이 저장한다.

1. clone 주소와 package fetch 주소를 먼저 적는다.
2. context fetch 인증인지 RUN 단계 인증인지 나눈다.
3. SSH mount와 secret mount를 소비 단계에 맞게 선택한다.
4. runtime secret은 final image 밖으로 분리한다.
5. history와 build log 검사 결과를 release 메모에 남긴다.

예를 들어 git@github.com clone이면 SSH mount가 더 직접적이고, private npm package를 install하면서 토큰 파일을 읽어야 하면 secret mount가 더 직관적이다. 반대로 애플리케이션 실행 뒤에도 필요한 credential은 build secret으로 해결하려고 하면 안 된다. build-only secret과 runtime secret은 회전 시점과 감사 포인트가 다르다.

점검 메모 예시

context_repo=git@github.com:example/private-lib.git
context_auth=ssh
run_secret=npm_token
runtime_secret=not-in-image
history_checked=true
logs_checked=true
credential_echo_found=false

이렇게 남겨 두면 다음 빌드에서 인증 문제가 생겨도 SSH 경로인지 token 경로인지 바로 갈린다. build 보안은 mount 문법보다 소비 단계와 흔적 검사가 더 중요하다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 화면은 Docker build secrets 문서의 SSH mounts 구간이다. private Git clone이 필요한 build에서 가장 먼저 갈라야 할 축은 token 파일을 넣을지, SSH agent나 key를 전달할지다.

Docker는 build secret과 별도로 SSH mount를 제공하고, private Git clone 같은 SSH 기반 fetch에 쓰라고 설명한다.

즉 모든 private fetch를 secret 파일 하나로 처리할 필요는 없다. clone 대상이 SSH 주소인지, build instruction 안에서 토큰 파일을 읽는지부터 분리해야 build 흔적 검사도 짧아진다.

두 번째 자료는 같은 문서의 Git authentication for remote contexts 구간이다. 이 부분은 remote Git context 자체를 builder가 먼저 받아야 할 때 쓰는 pre-flight secret을 설명한다.

Docker는 private remote Git context를 가져올 때 build instruction 안 secret과 다른 사전 인증 경로가 필요하다고 설명한다.

여기서 중요한 점은 secret이 Dockerfile 안에서 소비되지 않을 수 있다는 사실이다. context fetch 단계 인증과 RUN 단계 인증을 같은 로그 메모에 섞으면 원인 분리가 느려진다.

세 번째 공식 화면은 Build context 문서의 인증 설명이다. Docker는 private Git context를 받을 때 SSH와 token-based authentication을 둘 다 허용하고, SSH 주소라면 기본적으로 SSH credentials를 감지해 쓴다고 적고 있다.

Docker build context 문서는 private Git context에서 SSH와 token 기반 인증을 모두 지원한다고 설명한다.

따라서 질문은 '어느 쪽이 더 멋진가'가 아니라, 현재 저장소 주소와 조직 보안정책이 어떤 인증 흔적을 남기게 하는가다. clone 주소와 빌드 단계 secret 소비를 분리해 기록해야 한다.

네 번째 자료는 clone 경로와 secret 수명 주기를 같이 놓은 판단표다. private Git clone은 SSH mount가 더 자연스러운 경우가 많지만, build 중 API token을 파일이나 env로 읽는 install step은 secret mount가 더 직접적일 수 있다.

private Git clone build에서 SSH mount와 secret mount를 나누는 판단표다.

이미 build secrets와 ARG·ENV를 나누는 글이 build-only secret의 큰 분기를 다뤘다면, 이번 표는 private Git fetch에서 SSH와 token file을 더 좁게 나누는 단계다.

마지막 자료는 실무 예시다. 같은 Dockerfile 안에서 secret mount와 SSH mount를 어떤 자리에서 쓰는지, 그리고 빌드 뒤 어떤 history 검사를 붙이면 되는지 한 장에 모았다.

SSH mount, secret mount, history 검사 명령을 한 번에 묶은 예시다.

핵심은 build가 끝난 뒤에도 흔적을 닫는 일이다. ARG와 ENV에 비밀값을 넣으면 안 되는 글과 같이 보면 build-only secret과 runtime secret을 더 분명하게 나눌 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 SSH clone인데도 토큰 secret만 늘려 실제 원인을 가리는 것이다. 두 번째 리스크는 secret mount를 쓰고도 build script가 민감값을 echo 해 버리는 것이다. 세 번째 리스크는 remote context fetch 실패를 Dockerfile 내부 문제로만 오해하는 것이다.

운영 전에는 최소한 clone 주소, auth method, Dockerfile mount 방식, docker history 결과, build log 결과 다섯 칸을 한 메모에 두는 편이 좋다. 그래야 공급망 경로와 final image 흔적을 같이 설명할 수 있다.

• SSH clone과 token install은 같은 mount로 뭉뚱그리지 않는다.
• remote Git context 인증은 Dockerfile 실행 전 단계로 따로 본다.
• history와 build log 검사를 release 절차에 넣는다.

6. 결론

private Git clone이 필요한 Docker build는 mount 종류보다 인증 소비 단계를 먼저 나누는 편이 빠르다. SSH clone이면 SSH mount, RUN 단계 token 소비면 secret mount, final image 밖 runtime secret, 그리고 마지막 history와 log 검사까지 붙이면 재현과 감사가 모두 짧아진다.

• clone 주소와 소비 단계를 먼저 적는다.
• SSH mount와 secret mount를 상황별로 분리한다.
• build log와 docker history로 흔적을 닫는다.

7. 참고 링크

1. https://docs.docker.com/build/building/secrets/
2. https://docs.docker.com/build/concepts/context/
3. https://docs.docker.com/reference/dockerfile/
4. https://docs.docker.com/docker-and-private-modules/