Bitbucket 410 Gone 에러 해결 가이드

어느 날 평화롭게 인텔리제이를 켜고 Git Clone을 누르는 순간, 화면에 시뻘건 글씨로 410 Gone 에러가 빵 터진다면 얼마나 당황스러우셨을까요. 어제까지 잘만 되던 깃이 갑자기 나를 거부하는 배신감은 말로 다 표현할 수 없습니다.

서버가 터진 건가 싶어 사이트에 들어가 보면 웹페이지는 멀쩡히 잘 열립니다. 이 야속한 Bitbucket 410 Gone 에러가 왜 발생하는지 원인부터 파악하고, 인텔리제이와 맥 환경에서 확실하게 해결하는 방법까지 속 시원하게 정리해 드리겠습니다.

---

도대체 410 Gone 에러가 왜 뜨는 걸까요

개발을 하다 보면 403 Forbidden이나 404 Not Found는 자주 보지만, 410 Gone은 은근히 낯선 에러 코드입니다. HTTP 상태 코드에서 410은 요청한 리소스가 영구적으로 사라졌음을 의미합니다. 단순한 일시적 오류가 아니라, 네가 쓰던 방식은 이제 지구상에서 사라졌으니 꿈 깨라는 뜻입니다.

이 에러가 발생하는 이유는 아틀라시안의 보안 정책 변경 때문입니다. 비트버킷은 기존에 널리 쓰이던 구버전 앱 패스워드 인증 방식을 완전히 중단하고 폐기했습니다. 대신 더 강력하고 안전한 스코프 기반의 API 토큰 또는 개인 액세스 토큰 인증 방식을 도입했습니다.

따라서 내 컴퓨터나 인텔리제이가 기억하고 있는 인증 정보가 옛날 앱 패스워드라면, 비트버킷 서버는 이를 단칼에 거절하며 410 Gone이라는 응답을 던지게 됩니다. 해결책은 명확합니다. 비트버킷에서 권한이 제대로 설정된 새 API 토큰을 발급받고, 내 컴퓨터가 붙들고 있는 낡은 자격 증명을 깨끗하게 밀어버린 뒤 새 토큰을 주입하면 됩니다.

---

1단계 올바른 권한을 가진 새 API 토큰 발급받기

가장 먼저 해야 할 일은 새로운 인증 수단인 토큰을 만드는 것입니다. 그냥 아무 생각 없이 다음 버튼만 눌러서 토큰을 만들면, 나중에 푸시나 브랜치 생성 단계에서 또 에러를 마주하게 됩니다. 일반적인 개발자가 데일리로 사용하는 권한들을 꼼꼼하게 체크해서 발급받아야 합니다.

비트버킷 토큰 생성 절차

1. 비트버킷 클라우드 웹사이트에 로그인합니다.
2. 화면 좌측 하단에 있는 본인의 프로필 아바타 아이콘을 클릭한 뒤 개인 설정으로 들어갑니다.
3. 액세스 관리 메뉴에서 개인 액세스 토큰 또는 앱 패스워드 메뉴를 선택합니다.
4. 새 토큰 만들기 버튼을 클릭합니다.

개발자 필수 권한 스코프 목록

토큰을 만들 때 체크박스를 선택하는 화면이 나옵니다. 여기서 아래 항목들은 무조건 켜주셔야 정상적인 개발 프로세스가 굴러갑니다.

• 리포지토리 권한 (Repositories): 반드시 읽기와 쓰기를 모두 체크해야 합니다. 이 권한이 있어야 코드 복제는 물론이고 내가 작업한 코드를 원격 서버에 푸시할 수 있습니다.
• 풀 리퀘스트 권한 (Pull Requests): 읽기와 쓰기를 체크합니다. 로컬에서 브랜치를 푸시한 다음 메인 코드에 합치려면 PR을 날려야 하는데, 인텔리제이 내부에서 이 작업을 연동하려면 필수적입니다.
• 계정 권한 (Account): 읽기 권한을 부여합니다. 인텔리제이 같은 외부 도구가 비트버킷과 통신할 때 현재 로그인한 유저가 올바른 유저인지 검증하는 최소한의 장치입니다.

토큰 생성을 완료하면 화면에 엄청나게 긴 외계어 같은 문자열이 딱 한 번 나타납니다. 이 창을 닫으면 두 번 다시 토큰 값을 보여주지 않으니, 메모장이나 안전한 곳에 즉시 복사해 두셔야 정신 건강에 이롭습니다.

---

2단계 맥 키체인 및 Git 자격 증명 완벽하게 밀어버리기

새 토큰을 잘 복사해 뒀으니 신나게 인텔리제이로 가서 다시 Clone을 눌러봅니다. 그런데 이상하게 로그인 창도 안 뜨고 똑같이 410 에러를 뱉는 경우가 허다합니다. 내 영리하고 집요한 맥북이 옛날 패스워드를 키체인이나 메모리 깊은 곳에 꽁꽁 숨겨두고 재활용하고 있기 때문입니다. 이 과거의 흔적들을 강제로 지워줘야 합니다.

맥 키체인 접근에서 삭제하기

1. 커맨드와 스페이스바를 동시에 눌러 스포트라이트를 켭니다.
2. 키체인 접근을 입력하고 실행합니다.
3. 우측 상단 검색창에 bitbucket을 검색합니다.
4. 종류가 인터넷 암호 또는 응용 프로그램 암호로 되어 있는 항목을 찾습니다. 보통 주소가 bitbucket.org 형태로 되어 있습니다.
5. 해당 항목을 마우스 우클릭한 뒤 삭제를 선택하여 완벽하게 날려버립니다.

터미널에서 Git 인증 캐시 강제 초기화하기

키체인을 지웠는데도 구버전 정보가 계속 호출된다면 Git 자체의 크리덴셜 헬퍼가 범인입니다. 맥 터미널을 열고 아래의 명령어를 입력하여 비트버킷 관련 인증 캐시를 강제로 증발시켜 줍니다.

git credential-osxkeychain erase host=bitbucket.org protocol=https

명령어를 치고 엔터를 눌렀을 때 아무런 메시지도 안 뜨고 그냥 다음 줄로 넘어가면 아주 깔끔하게 성공한 것입니다. 에러 메시지가 없다는 것이 최고의 아웃풋입니다.

---

3단계 인텔리제이에서 새 토큰으로 복제 성공하기

컴퓨터에 남아있던 낡은 자격 증명까지 모두 청소했다면 이제 인텔리제이를 완전히 종료했다가 다시 켭니다. 새로 복제를 진행하는 방법은 크게 두 가지가 있습니다. 본인 입맛에 맞는 편한 방식을 선택하시면 됩니다.

방법 A 주소창에 토큰 직접 때려 넣기

자격 증명 창이 뜨네 마네 밀당하는 것이 짜증 난다면 주소창에 내 토큰 정보를 직접 박아서 명령을 내리는 것이 가장 확실하고 속 편합니다. 인텔리제이 깃 복제 메뉴에서 URL 입력란에 아래와 같은 형식으로 주소를 수정하여 입력합니다.

• 원래 주소 형식: bitbucket.org
• 변경할 주소 형식: https://토큰값@bitbucket.org/workspace/project.git

이렇게 주소 자체에 인증 수단을 포함해 버리면 인텔리제이가 비트버킷 서버에 접근할 때 통행증을 미리 보여주는 격이라 따로 로그인 팝업을 띄우지 않고 곧바로 복제를 시원하게 완료해 줍니다.

방법 B 인텔리제이 자격 증명 기능 이용하기

정석적인 방법을 원하신다면 원래의 비트버킷 주소를 그대로 넣고 복제 버튼을 누릅니다. 이전 단계에서 캐시를 완벽히 밀었기 때문에 이번에는 인텔리제이가 당황하며 로그인 창을 띄울 것입니다.

• 사용자 이름 (Username): 비트버킷 계정의 이메일 주소가 아니라 본인의 고유 유저네임을 입력합니다.
• 비밀번호 (Password/Token): 일반 비밀번호나 옛날 앱 패스워드가 아닌, 조금 전 1단계에서 발급받아 복사해 둔 새 API 토큰 값을 그대로 붙여넣기 합니다.

---

4단계 설정을 다 마쳤는데도 안 될 때 최종 점검 리스트

인증 정보도 새것으로 바꿨고 토큰 권한도 다 켰는데 여전히 특정 상황에서 에러가 발생한다면 기술적인 영역 외에 권한 프로세스나 보안 정책을 의심해 봐야 합니다.

저장소 자체의 멤버십 권한 확인

토큰에 리포지토리 쓰기 권한을 아무리 빵빵하게 줘봤자, 내 비트버킷 계정 자체가 해당 프로젝트나 팀 저장소에서 추방당했거나 접근 권한이 없다면 무용지물입니다. 프로젝트 관리자에게 요청하여 내 계정에 최소 쓰기(Write) 권한이 제대로 할당되어 있는지 확인해 달라고 하셔야 합니다.

브랜치 제한 정책 체크

복제도 잘 되고 코드 수정도 다 했는데 유독 특정 브랜치에 푸시를 할 때만 에러가 튕겨 나간다면, 십중팔구 브랜치 프로텍션 정책 때문입니다. 대다수의 현업 프로젝트는 메인(main)이나 디벨롭(develop) 브랜치에 개발자가 직접 코드를 푸시하는 행위를 막아둡니다.

이럴 때는 당황하지 마시고 로컬에서 개인 작업용 브랜치를 새로 하나 만드셔야 합니다.

git checkout -b feature/my-cool-feature

이렇게 새로운 브랜치를 파서 작업을 진행한 뒤, 이 브랜치 명 그대로 원격 저장소에 푸시를 올리면 정상적으로 업로드됩니다. 그 이후 비트버킷 웹페이지에 접속해서 메인 브랜치로 합쳐달라는 풀 리퀘스트를 날리는 것이 안전하고 올바른 협업 프로세스입니다.

갑작스러운 정책 변화로 개발 흐름이 끊기면 스트레스를 받기 마련이지만, 차근차근 순서대로 인증 정보를 갱신해 주면 금방 해결할 수 있습니다. 모두 에러 없는 쾌적한 코딩 생활을 즐기시기 바랍니다.