비공개 패키지를 설치하려고 Docker 빌드에 접근 토큰을 넘길 때, 실행 컨테이너에서 토큰이 안 보인다는 이유만으로 안전하다고 판단하면 안 된다. 전달 경로와 빌드 결과, 로그, 캐시를 따로 점검해야 한다. 2026년 10월 27일 Docker 공식 문서를 기준으로 작은 팀이 확인할 항목을 정리했다.
ARG가 실행 환경변수로 안 남아도 안전한 것은 아니다
Docker 문서에 따르면 ARG는 Dockerfile의 설정을 매개변수화하는 용도다. 명시적으로 전달하지 않으면 실행 컨테이너에서 그대로 사용할 수 없지만, 이미지 메타데이터·출처 증명·히스토리에는 남을 수 있다. ENV는 이미지에서 시작하는 컨테이너에도 지속된다. 두 방식 모두 비밀값을 빌드에 전달하는 용도로 적합하지 않다. Docker 빌드 변수 안내
따라서 런타임 환경변수 목록 하나만 확인하는 검사는 충분하지 않다. 예를 들어 “실행 컨테이너에 없으니 이미지와 빌드 기록에도 없다”는 결론은 피해야 한다. 일반적인 버전 번호 같은 공개 설정과 접근 토큰을 구분하는 것이 출발점이다.
빌드에 필요한 비밀값은 별도 마운트로 전달한다
Docker가 안내하는 secret mount는 빌드 클라이언트의 비밀값을 해당 빌드 명령 동안 임시로 제공한다. 빌드 명령에 --secret으로 전달하고 Dockerfile의 RUN에서 --mount=type=secret으로 소비하는 두 단계다. 소스는 파일 또는 환경변수일 수 있고, 빌드 안에서는 파일이나 환경변수 형태로 제공할 수 있다. Docker Build secrets
여기서 환경변수 소스를 사용한다는 말은 Dockerfile에 ENV로 비밀값을 저장한다는 뜻과 다르다. 전달하는 인터페이스와 값을 읽는 명령을 함께 확인해야 한다. 비밀값의 실제 내용 대신 식별자·용도·사용 단계만 문서화하자.
마운트가 임시라는 사실만으로 그 값을 읽은 명령의 행동까지 안전해지는 것은 아니다. 명령이 토큰을 로그에 출력하거나 결과 파일에 복사하지 않는지 확인해야 한다. 이는 임시 전달 방식의 범위에서 도출되는 운영상 주의점이다. 패키지 도구의 진단 출력이나 생성 설정 파일도 점검 대상에 포함한다.
.dockerignore는 전달 제외 규칙이지 비밀 주입 기능이 아니다
.dockerignore는 빌드 컨텍스트에서 파일을 제외하는 규칙이다. 일치하는 파일은 빌더로 보내기 전에 컨텍스트에서 제거된다. 별도 Dockerfile용 ignore 파일이 있으면 루트의 .dockerignore보다 우선한다. Docker 빌드 컨텍스트 설명
팀에서는 로컬 설정 파일을 제외했는지와 빌드에 필요한 토큰을 별도 경로로 전달하는지를 각각 확인해야 한다. 한쪽 설정만으로 다른 쪽이 해결됐다고 보면 안 된다. 빌드 명령이 어느 디렉터리를 컨텍스트로 사용하는지, 어떤 Dockerfile과 ignore 파일을 선택했는지도 기록해 두자.
토큰 값만 바꾸면 캐시가 갱신될까?
공식 캐시 문서는 secret의 내용이 빌드 캐시의 일부가 아니므로 값 변경만으로 캐시가 무효화되지 않는다고 설명한다. 반면 secret ID와 마운트 경로 같은 속성은 캐시 체크섬에 참여한다. 빌드 secret과 캐시 무효화
예를 들어 다른 입력은 그대로인 상태에서 패키지 접근 토큰만 바꿨다면, 빌드 성공이 새 토큰으로 실제 인증했다는 증거는 아닐 수 있다. 캐시된 단계가 재사용됐는지부터 확인해야 한다. 아래 비교는 공식 동작을 정리한 것으로 실제 테스트 결과가 아니다.
- secret 값만 변경: 그 변경 자체로 캐시 무효화가 발생하지 않는다.
- secret ID 변경: 캐시 판정에 영향을 주는 속성 변경이다.
- 마운트 경로 변경: 역시 캐시 체크섬에 참여하는 속성 변경이다.
새 인증을 시험하려면 관련 단계가 실제로 다시 실행되도록 제어하는 절차가 필요하다. Docker 문서는 secret 변경 시 함께 바꾸는 임의의 빌드 인자를 사용하는 방법도 설명한다. 이 인자에는 토큰 자체가 아니라 공개 가능한 갱신 번호 등을 사용해야 한다. 캐시 재실행을 인증 성공으로 단정하지 말고, 필요한 다운로드가 새 실행에서 성공했는지도 구분해 확인한다.
팀 인수인계에 남길 네 가지 검증 항목
다음은 문서를 바탕으로 구성한 운영 점검표다. 실제 비밀값을 보고서나 이슈에 붙여 넣는 방식으로 검사하지 않는다.
- 입력 경로: 공개 설정은 일반 빌드 변수로, 비밀값은 secret 전달 경로로 구분했는지 확인한다. 담당자와 용도를 기록하되 값은 기록하지 않는다.
- 컨텍스트: 선택된 컨텍스트·Dockerfile·ignore 파일을 확인하고, 불필요한 로컬 비밀 파일이 포함되지 않도록 점검한다.
- 출력 경로: 빌드 로그, 생성 설정 파일, 이미지 메타데이터와 최종 산출물에 비밀값이 남는지 조직이 승인한 검사 방법으로 확인한다. 한 번의 문자열 검색만으로 모든 형태의 노출이 없다고 보장하지 않는다.
- 재검증: 비밀값 변경 뒤 실제로 재실행된 단계와 인증 결과를 구분해 기록한다. 시험용 비민감 값으로 전달 경로를 먼저 검증하면 실수로 운영 토큰을 출력하는 위험을 줄일 수 있다.
이미 비밀값 노출이 의심된다면 새 Dockerfile만 배포하고 끝내지 말고, 발급 서비스와 조직의 절차에 따라 기존 자격증명 및 노출된 산출물의 처리를 검토해야 한다. 이 글은 실제 계정의 키 생성·교체·폐기를 수행하지 않는다.
재빌드에는 환경별 컴퓨팅·네트워크 비용이 생길 수 있다. 특정 금액·통화·세금·약정 할인이나 비용 절감률은 제시하지 않는다. 빌드 결과 파일의 보관 정책은 GitHub Actions 아티팩트 보관 기간 점검도 함께 참고할 수 있다.
AI 에이전트가 공식 출처와 설명을 검토했다. 이미지는 개념 비교용이며 실제 토큰, 운영 계정 화면 또는 실측 결과를 포함하지 않는다.