GitLab SMTP 메일 발송 오류 – Gmail App Password 필요 이슈

GitLab SMTP 메일 발송 오류 – Gmail App Password 필요 이슈

GitLab을 Docker 기반의 온디맨드 환경에서 운영하던 중,
기존에 정상적으로 작동하던 메일 발송 기능이 어느 순간부터 갑자기 실패하기 시작했습니다.

당시 SMTP 설정은 Gmail 계정의 ID와 비밀번호를 이용해 아래와 같이 구성되어 있었습니다:

gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "noreply@yourdomain.com"
gitlab_rails['smtp_password'] = "일반계정패스워드"
gitlab_rails['smtp_domain'] = "smtp.gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

하지만 갑작스레 메일 발송이 되지 않으면서, 아래와 같은 오류 메시지가 출력되었습니다:

Net::SMTPAuthenticationError: 534-5.7.9 Application-specific password required

---

원인 분석

Gmail은 2022년부터 보안 정책을 강화하면서,
일반 비밀번호를 이용한 SMTP 인증을 더 이상 지원하지 않도록 변경했습니다.

SMTP와 같은 외부 서비스에서는 반드시 앱 비밀번호(App Password) 를 사용해야 하며,
기존의 Gmail 계정 ID/비밀번호 조합으로는 더 이상 인증이 되지 않습니다.

🔒 App Password란?

2단계 인증(2FA)이 활성화된 Gmail 계정에서 발급할 수 있는
특정 앱 전용의 16자리 비밀번호입니다.
GitLab, Jenkins 등과 같은 서비스에서 SMTP 연동 시 필수적으로 사용해야 합니다.

---

해결 방법

1. Gmail 계정에 로그인 후 App Password 생성 페이지에 접속합니다.
2. 앱 선택: "Mail", 기기 선택: "Other" → 예: GitLab 등으로 입력 후 생성
3. 생성된 16자리 앱 비밀번호를 복사하여 smtp_password 항목에 입력합니다.

gitlab_rails['smtp_password'] = "vyjhxxxxxxxxxxxx"  # 생성된 앱 비밀번호 입력

4. GitLab 서버에서 설정을 반영합니다:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

---

참고 링크

• 📄 Google 공식 문서 - 앱 비밀번호 사용
• 📄 2단계 인증 안내

---

마무리

Google의 보안 정책 변경으로 인해 SMTP 인증 방식도 함께 바뀌었습니다.
기존처럼 Gmail 계정의 일반 비밀번호로는 더 이상 인증이 되지 않으며,
App Password를 이용한 인증 방식으로 전환해야만 메일 발송이 정상적으로 작동합니다.

GitLab, Jenkins, WordPress 등 SMTP를 활용하는 모든 환경에서
이 변경 사항을 반드시 반영해야 하므로 참고하시기 바랍니다.