**GitHub Actions + SSH (appleboy/ssh-action)**를 사용하여 애플리케이션을 배포하고 **GitHub Container Registry (GHCR)**에서 이미지를 가져올 때, 다음과 같은 두 가지 일반적인 오류가 함께 발생하는 경우가 많습니다:

• GHCR에서 Docker 이미지를 가져올 때 발생하는 unauthorized 오류
• Cannot perform an interactive login from a non TTY device 오류

이 오류들은 보통 혼란스러워 보이지만, 둘 다 동일한 근본 원인에서 비롯됩니다: 비대화형 환경 (CI/CD 또는 SSH 자동화)에서 Docker 인증 (Authentication)이 올바르게 처리되지 않았기 때문입니다.

이 글에서는 어떤 일이 일어나고 있는지, 왜 실패하는지, 그리고 이를 영구적으로 해결하는 방법을 설명합니다.

문제 상황 (로그에서 보이는 내용)

1. GHCR Unauthorized 오류

Error response from daemon:
Head "https://ghcr.io/v2/ORG/REPO/manifests/latest": unauthorized

이는 Docker가 GHCR에서 프라이빗 이미지를 가져오려고 시도했으나 인증되지 않았음을 의미합니다.

2. Non-TTY 로그인 오류

Error: Cannot perform an interactive login from a non TTY device

이는 Docker가 다음 명령을 실행하려고 시도했음을 의미합니다:

docker login ghcr.io

하지만 다음과 같은 이유로 실패했습니다:

GitHub Actions와 SSH 스크립트는 대화형 입력 (사용자 이름/비밀번호를 입력할 터미널)을 지원하지 않습니다.

근본 원인

두 오류 모두 동일한 문제에서 발생합니다:

Docker 로그인 상태가 다음과 같습니다:

• 완전히 누락됨 ❌
• 또는 대화형 모드로 작성됨 ❌
• 또는 자격 증명 (Credentials)을 올바르게 전달받지 못함 ❌

CI/CD 환경에서는:

• 키보드 입력이 없습니다.
• 터미널 (TTY)이 없습니다.
• 모든 것이 완전히 자동화되어야 합니다.

올바른 사고 모델

GHCR을 개인 건물이라고 생각해보세요:

• docker pull = 건물에 들어가려고 시도하는 것
• docker login = 신분증을 보여주는 것

들어가기 전에 신분증을 보여주지 않으면 다음과 같은 결과가 발생합니다:

❌ unauthorized

자동화 과정에서 "비밀번호를 수동으로 입력"하려고 하면 다음과 같은 결과가 발생합니다:

❌ non-TTY error

올바른 해결책 (운영 환경용 솔루션)

1단계: GitHub 토큰 (PAT) 생성

다음 경로로 이동하세요:

GitHub → Settings → Developer Settings → Personal Access Tokens

다음 권한을 가진 토큰을 생성하세요:

• read:packages ✅
• repo (프라이빗 리포지토리인 경우) ✅

Step 2: GitHub Actions에 Secrets 저장하기

다음 Secret들을 추가하세요:

• GHCR_USERNAME → 귀하의 GitHub 사용자 이름
• GHCR_TOKEN → 귀하의 Personal Access Token

Step 3: SSH Action에 Secrets 전달하기

GitHub Actions 워크플로(workflow)에서:

- name: Deploy via SSH
  uses: appleboy/ssh-action@v1.2.5
  with:
...

Step 4: 비대화형 (Non-Interactive) Docker 로그인 사용 (중요)

✔️ 올바른 방법:

echo $GHCR_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin

잘못된 방법 (TTY 오류 발생):

docker login ghcr.io

Step 5: 서버에서 로그인 확인하기

다음 명령어를 실행하세요:

cat ~/.docker/config.json

로그인이 성공했다면, 다음과 같은 내용을 볼 수 있습니다:

"auths": {
  "ghcr.io": {
    "auth": "..."
...

최종 배포 흐름 (올바른 순서)

SSH 배포 스크립트는 항상 다음 패턴을 따라야 합니다:

set -e

echo "Logging into GHCR..."
...

이 문제를 일으키는 흔한 실수들

1. 대화형 (Interactive) 로그인 사용

docker login ghcr.io

❌ CI/CD 환경에서 작동하지 않음

2. SSH로 환경 변수(Environment Variables) 전달 누락

만약 다음 내용을 포함하지 않는다면:

envs: GHCR_TOKEN,GHCR_USERNAME

서버는 빈 값을 받게 되며 → 로그인이 조용히 실패합니다.

3. 잘못된 이미지 이름 또는 태그 사용

예시:

ghcr.io/org/repo:latest

다음 사항을 확인하세요:

• 이미지가 존재하는지
• 태그가 존재하는지 (latest 또는 버전 태그)

4. 패키지 권한 누락

토큰에는 반드시 다음 권한이 있어야 합니다:

• read:packages

그렇지 않으면 GHCR은 항상 unauthorized를 반환합니다.

왜 DevOps 자동화에서만 이 문제가 발생하는가

이 문제는 다음 환경에서 매우 흔하게 발생합니다:

• GitHub Actions
• Docker CI/CD 파이프라인 (pipelines)
• SSH 배포 스크립트
• Kubernetes 초기화 컨테이너 (init containers)

그 이유는 이 모든 환경이 다음과 같기 때문입니다:

비대화형 환경 (Non-interactive environments, 인간의 입력이 허용되지 않음)

요약

딱 한 가지만 기억해야 한다면:

❗ CI/CD에서의 GHCR pull 실패 = 언제나 인증(authentication) 문제

그리고:

• unauthorized → 유효한 로그인이 없음
• non-TTY login error → 대화형 로그인을 잘못 사용함

최종 작동 체크리스트

✔ docker login --password-stdin 사용
✔ SSH로 시크릿(secrets) 전달 (envs:)
✔ 토큰에 read:packages 권한이 있는지 확인
✔ GHCR에 이미지가 존재하는지 확인
✔ CI/CD에서 대화형(interactive) 명령 사용을 피할 것

이 내용이 도움이 되었다면, 저는 YouTube, Hashnode, Dev.to에서 DevOps, 인프라(infrastructure), 백엔드 엔지니어링(backend engineering)에 관한 콘텐츠를 제작하고 있습니다. 이러한 방식의 문제 해결 방법을 더 보고 싶으시다면 팔로우해 주세요.