오류: HTTP Basic: Access denied. If a password was provided for Git authentication ...#

요청 시 다음과 같은 오류가 발생할 수 있습니다:

HTTP Basic: Access denied. If a password was provided for Git authentication,
the password was incorrect or you're required to use a token instead of a password.
If a token was provided, it was either incorrect, expired, or improperly scoped.

이 오류는 다음과 같은 경우에 발생합니다:

• 2FA를 활성화했고 사용자 이름과 비밀번호로 인증을 시도한 경우.

• 2FA를 활성화하지 않았지만 GitLab 인스턴스에서 2FA가 필수인 경우. 이는 GitLab.com에 적용됩니다. 자세한 내용은 필수 MFA 변경 사항 및 이메일 OTP 트러블슈팅을 참조하세요.

• 2FA를 활성화하지 않았고 잘못된 사용자 이름 또는 비밀번호로 인증을 시도한 경우.

• 2FA를 활성화하지 않았고 모든 사용자에게 2FA 적용 설정이 활성화된 경우.

• 2FA를 활성화하지 않았고 Allow password authentication for Git over HTTP(S) 체크박스가 선택되지 않은 경우.

이 오류를 해결하려면:

• 올바른 스코프를 가진 개인 액세스 토큰을 사용합니다:

HTTP(S)를 통한 Git 요청의 경우: read_repository 또는 write_repository

• GitLab 컨테이너 레지스트리 요청의 경우: read_registry 또는 write_registry

• 의존성 프록시 요청의 경우: read_registry 및 write_registry

• LDAP를 구성한 경우 LDAP 비밀번호를 사용합니다.

• OAuth 자격 증명 헬퍼를 사용합니다.

오류: invalid pin code#

invalid pin code 오류는 인증 애플리케이션과 GitLab 인스턴스 간의 시간 동기화 문제를 나타낼 수 있습니다.

이 문제를 해결하려면 2FA 코드를 생성하는 기기에서 시간 동기화를 활성화하세요.

오류: 복구 코드 생성 시 Permission denied (publickey)#

Permission denied (publickey) 오류가 발생할 수 있습니다.

이 문제는 기본이 아닌 SSH 키 쌍 파일 경로를 사용하고 SSH를 사용하여 복구 코드를 생성하려는 경우 발생합니다.

이를 해결하려면 ssh-agent를 사용하여 다른 디렉터리를 가리키도록 SSH를 구성하세요.

이메일 OTP 트러블슈팅#

이메일 OTP를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

2026년 4월부터 GitLab.com에서 사용자 이름과 비밀번호를 사용하는 로그인 또는 API 요청에 대해 다단계 인증이 의무화됩니다. 다른 인증 수단이 구성되어 있지 않은 경우 이메일 OTP가 GitLab.com의 필수 두 번째 인증 수단입니다.

향상된 인증 배너 및 패스코드 요구 사항#

Enhanced Authentication Coming Soon 배너는 GitLab이 비밀번호 기반 로그인 시 계정에 이메일 일회성 패스코드 적용을 시작할 것임을 알립니다. SSO로 로그인하거나 이미 2FA를 구성한 사용자는 영향을 받지 않습니다.

이 배너는 적용 14일 전에 표시됩니다. 적용 7일 전부터는 GitLab이 비밀번호 기반 로그인마다 일회성 패스코드를 전송합니다. 이 기간 동안 패스코드 입력을 건너뛸 수 있습니다.

적용 날짜가 지나면 모든 비밀번호 기반 로그인 시 일회성 패스코드를 입력해야 합니다. 잠기는 것을 방지하려면 기본 이메일 주소에 접근할 수 있는지 확인하거나 기본 이메일 주소를 변경하세요.

이메일 인증 코드를 받지 못했거나 코드가 만료된 경우#

이메일이 도착할 때까지 잠시 기다린 후 스팸 폴더를 확인하세요. GitLab.com의 경우 이메일은 gitlab@mg.gitlab.com에서 발송되며 진위 여부를 확인할 수 있습니다.

코드가 도착하지 않았거나 만료된 경우, 로그인 페이지에서 코드 재전송을 선택하세요. 재전송할 때마다 새 코드가 생성되고 이전 코드는 무효화되므로, 다시 요청하기 전에 각 이메일을 기다리세요.

이메일 주소에 접근할 수 없는 경우#

기본 이메일 주소에 접근할 수 없는 경우 계정과 연결된 다른 이메일 주소를 사용하세요. 로그인 페이지에서 이 계정과 연결된 다른 주소로 코드 보내기를 선택합니다.

연결된 이메일 주소에 모두 접근할 수 없는 경우:

• 이전에 SSO를 구성한 경우 사용자 이름과 비밀번호 대신 SSO로 로그인합니다.

• GitLab.com 엔터프라이즈 사용자인 경우 그룹 Owner에게 이메일 주소 변경을 요청합니다.

• GitLab Self-Managed에서는 GitLab 관리자에게 문의하세요.

• GitLab 지원에 문의하세요.

이메일 OTP를 활성화하거나 비활성화할 수 없는 경우#

다음의 경우 이메일 OTP를 비활성화할 수 없습니다:

• 인스턴스에서 2FA를 요구하는데 OTP 인증기 또는 WebAuthn 장치를 등록하지 않은 경우.

• 계정이 향후 날짜에 자동으로 활성화되도록 예약된 경우.

다음의 경우 이메일 OTP를 활성화할 수 없습니다:

• 그룹, 인스턴스 또는 관리 정책에서 OTP 인증기 또는 WebAuthn 장치를 사용하도록 요구하는 경우.

• 계정이 외부 ID 공급자를 사용하는 경우.

• 계정이 향후 날짜에 자동으로 활성화되도록 예약된 경우.

복구 옵션 및 2FA 재설정#

복구 코드 사용#

일회성 비밀번호(OTP) 인증기를 활성화하면 GitLab이 일련의 복구 코드를 제공합니다. 이 코드를 사용하여 계정에 로그인할 수 있습니다.

복구 코드를 사용하려면:

• GitLab 로그인 페이지에서 사용자 이름 또는 이메일과 비밀번호를 입력합니다.

• 이중 인증 코드를 입력하라는 메시지가 표시되면 복구 코드를 입력합니다.

복구 코드를 사용한 후에는 동일한 코드를 다시 사용할 수 없습니다. 다른 복구 코드는 계속 유효합니다.

UI로 복구 코드 재생성#

계정에 여전히 접근할 수 있는 경우 사용자 설정을 통해 복구 코드를 재생성할 수 있습니다.

UI로 복구 코드를 재생성하려면:

• 오른쪽 상단 모서리에서 아바타를 선택합니다.

• Edit profile을 선택합니다.

• 왼쪽 사이드바에서 Access > Password and authentication을 선택합니다.

• 복구 코드 섹션에서 복구 코드 재생성을 선택합니다.

• 대화 상자에서 현재 비밀번호를 입력하고 복구 코드 재생성을 선택합니다.

2FA 복구 코드를 재생성할 때마다 저장하세요. 이전에 생성된 2FA 코드는 사용할 수 없습니다.

SSH로 복구 코드 재생성#

GitLab 계정에 SSH 키를 추가한 경우 SSH로 복구 코드를 재생성할 수 있습니다.

필수 요건:

• GitLab 계정에 등록된 SSH 공개 키와 연결된 프라이빗 SSH 키에 접근할 수 있어야 합니다.

gitlab-sshd를 사용하여 복구 코드를 재생성할 수 없습니다.

SSH로 복구 코드를 재생성하려면:

터미널에서 기기에 SSH 에이전트가 실행 중인지 확인합니다.

macOS 및 Linux에서 다음 명령을 실행합니다:

eval "$(ssh-agent -s)"

Microsoft Windows에서 PowerShell에서 다음 명령을 실행합니다:

Set-Service -Name ssh-agent -StartupType Automatic; Start-Service ssh-agent

자세한 내용은 Windows에서 SSH 사용을 참조하세요.

다음 명령으로 SSH 에이전트에 프라이빗 키를 로드합니다:

macOS 및 Linux에서 다음 명령을 실행합니다:

ssh-add <directory to private SSH key>

자세한 내용은 다른 디렉터리에서 SSH 키 사용을 참조하세요.

다음 명령으로 SSH 연결을 엽니다:

ssh git@gitlab.com 2fa_recovery_codes

GitLab Self-Managed 인스턴스의 경우 gitlab.com을 GitLab 서버 호스트 이름(gitlab.example.com)으로 교체합니다.

확인 메시지에서 yes를 입력합니다.

GitLab이 생성하는 복구 코드를 저장합니다. 이전 복구 코드는 더 이상 유효하지 않습니다.

로그인 페이지에서 사용자 이름 또는 이메일과 비밀번호를 입력합니다.

이중 인증 코드를 입력하라는 메시지가 표시되면 새 복구 코드 중 하나를 입력합니다.

로그인 후 즉시 새 기기로 2FA를 설정하세요.

인증기 백업에서 2FA 코드 복원#

GitLab 복구 코드 외에도 많은 인증기 앱이 자체 백업 및 복구 방법을 제공합니다. 기기를 분실한 경우 사전에 백업 기능을 활성화한 경우 새 기기에서 인증기 앱에 로그인하여 2FA 코드를 복원할 수 있습니다.

필수 요건:

• 기기에 대한 접근 권한을 잃기 전에 인증기 백업 기능을 활성화해야 합니다.

GitLab은 복구 코드를 기본 복구 방법으로 사용하도록 권장합니다. 2FA를 활성화할 때 복구 코드를 저장해야 합니다.

GitLab 지원은 서드 파티 인증기 앱과 관련된 복구 문제를 지원할 수 없습니다.

자세한 내용은 특정 인증기 앱의 문서를 참조하세요. 일반 인증기에 대한 문서는 다음 위치에서 확인할 수 있습니다:

• Microsoft Authenticator

• Google Authenticator

• Authy

• 1Password

계정에서 2FA 재설정#

이전 복구 옵션이 작동하지 않는 경우 계정의 2FA를 비활성화하기 위한 지원 요청을 생성할 수 있습니다. 이 서비스는 GitLab.com 구독이 있는 계정에만 사용할 수 있습니다.

GitLab 지원은 무료 계정의 2FA를 재설정할 수 없습니다. 2FA 방법을 복구할 수 없는 경우 계정에서 영구적으로 잠기게 되므로 새 계정을 만들어야 합니다. 자세한 내용은 블로그 공지를 참조하세요.

지원 요청을 생성하려면:

• GitLab 지원으로 이동합니다.

• 티켓 제출을 선택합니다.

• GitLab 지원 계정으로 로그인합니다. 지원 계정은 GitLab 계정과 다르며 2FA 문제의 영향을 받지 않습니다.

• 이슈 드롭다운 목록에서 GitLab.com 사용자 계정 및 로그인 문제를 선택합니다.

• 지원 양식의 필드를 작성합니다.

• 제출을 선택합니다.

계정에 다시 접근한 후 계정 보안을 위해 가능한 한 빨리 2FA를 다시 활성화하세요.

엔터프라이즈 사용자의 2FA 재설정#

유료 플랜의 최상위 그룹 Owner인 경우 엔터프라이즈 사용자의 2FA를 비활성화할 수 있습니다. 자세한 내용은 엔터프라이즈 사용자의 2FA 비활성화를 참조하세요.