# Docker Hub device flow
docker login

# self-hosted registry: host와 선택적 port만 지정
docker login registry.example.com
docker login registry.example.com:5000

# CI: secret 값은 표준 입력으로 전달
printf '%s' "$REGISTRY_TOKEN" | docker login registry.example.com \
  --username "$REGISTRY_USER" --password-stdin

# 인증 제거
docker logout registry.example.com

로그인 대상과 방법

docker login은 Docker Hub나 private registry에서 image를 pull/push하기 위한 인증을 설정합니다. Docker Hub는 기본적으로 device code flow를 사용하며, --username을 지정하면 사용자명 기반 로그인 흐름을 사용합니다. self-hosted registry에는 host와 선택적 port를 넘깁니다.

docker login
docker login --username my-user
docker login registry.example.com
docker login registry.example.com:1337

registry 주소에는 hostname과 선택적 port만 씁니다. registry.example.com/foo/처럼 path를 포함하면 올바른 registry 주소가 아니므로 오류가 날 수 있습니다. registry.example.com/team/api:1.2.3의 team/api는 image repository 경로이고 login 대상이 아닙니다.

credential store와 helper

Docker는 인증 정보를 credential store나 credential helper를 통해 OS keychain, Windows Credential Manager, pass 같은 외부 저장소에 보관할 수 있습니다. Docker Desktop은 보통 credential store가 이미 설치·설정되어 있습니다. credential store가 없으면 Docker는 $HOME/.docker/config.json 또는 Windows의 %USERPROFILE%\.docker\config.json에 base64 인코딩 형태로 저장할 수 있는데, 이 방식은 보안상 더 약합니다.

{
  "credsStore": "osxkeychain",
  "credHelpers": {
    "registry.example.com": "pass"
  }
}

registry별로 다른 helper를 쓰려면 credHelpers를 설정합니다. 일치하는 registry의 credHelpers는 공통 credsStore나 auths보다 우선합니다. helper 이름은 docker-credential-<name> 실행 파일의 <name> 부분이며, Docker client host의 $PATH에서 찾을 수 있어야 합니다.

이미 로그인한 상태에서 store 설정을 바꾸는 경우에는 docker logout으로 기존 자격 증명을 지우고 다시 로그인해야 설정이 명확하게 반영됩니다. Docker Desktop이 아닌 서버·CI runner에서는 helper 설치와 config.json 정책을 따로 확인합니다.

자동화 보안

CI에서는 token을 명령행 인자로 넘기지 말고 표준 입력으로 전달합니다. --password-stdin은 secret이 shell history나 로그에 남을 가능성을 줄입니다. 다만 job에 넓은 권한의 장기 token을 넣거나 shell trace를 켜면 여전히 노출 범위가 커집니다. registry별 최소 권한·짧은 만료·CI secret masking을 함께 적용하고, job이 끝나면 필요한 경우 docker logout 또는 일회성 Docker config directory를 사용합니다.