git push 가 거부될 때 나오는 메시지로 원인을 특정할 수 있습니다.
오류 유형별 빠른 찾기
| 오류 메시지 | 원인 |
|---|---|
Updates were rejected because the remote contains work | 원격에 내 로컬에 없는 커밋 존재 |
Updates were rejected because the tip of your current branch is behind | 원격보다 로컬이 뒤처짐 |
remote: error: GH006: Protected branch update failed | GitHub 보호 브랜치 |
remote rejected ... pre-receive hook declined | 서버 훅 또는 보호 규칙 |
원인 1 — non-fast-forward (가장 흔함)
원격에 다른 사람이 커밋을 push 한 상태에서 내 push 가 충돌합니다.
Bash
# 원격 상태 확인
git fetch origin
git log --oneline HEAD..origin/main # 원격에만 있는 커밋
git log --oneline origin/main..HEAD # 내 로컬에만 있는 커밋방법 A: rebase (권장 — 커밋 히스토리 깔끔)
Bash
git fetch origin
git rebase origin/main
# 충돌이 없으면 바로 push 가능
git push origin main충돌 발생 시:
Bash
# 충돌 파일 수정 후
git add 충돌파일
git rebase --continue
# 포기하고 되돌리기
git rebase --abort방법 B: merge
Bash
git fetch origin
git merge origin/main
git push origin main방법 C: pull --rebase (한 번에)
Bash
git pull --rebase origin main
git push origin main원인 2 — GitHub Protected Branch
Bash
# 오류 예시
# remote: error: GH006: Protected branch update failed
# remote: error: Required status check "CI" is failing.직접 push가 막혀 있습니다. 해결 방법:
- Pull Request로 병합 (정상적인 방법)
- GitHub 설정에서 보호 해제 (관리자 권한 필요)
- Repository → Settings → Branches → Branch protection rules
force push로 우회하는 것은 팀 작업 중에 타인의 커밋을 날릴 위험이 있습니다. PR 방식을 사용하세요.
원인 3 — 원격 브랜치와 현재 브랜치 이름 불일치
Bash
# 현재 브랜치 확인
git branch
# 원격 브랜치 목록
git branch -r
# 브랜치 명시 push
git push origin 로컬브랜치명:원격브랜치명
# 예: feature/login → origin의 feature/login
git push origin feature/login원인 4 — 원격 저장소가 bare가 아닌 경우
자체 호스팅 git 서버에서 원격 브랜치가 현재 checked out 상태이면 push를 거부합니다.
Bash
# 원격 서버에서 실행
git config --bool receive.denyCurrentBranch false
# 또는 bare 저장소로 설정
git config receive.denyCurrentBranch updateInstead원인 5 — 대용량 파일이 포함된 경우
Bash
# 오류 예시
# remote: error: File bigfile.zip is 120.00 MB; this exceeds GitHub's file size limit of 100.00 MB
# 해당 커밋에서 파일 제거
git log --oneline -5
git show --stat HEAD | grep 큰파일
# 마지막 커밋에서 파일만 제거
git rm --cached 큰파일.zip
echo "큰파일.zip" >> .gitignore
git commit --amend --no-edit대용량 파일은 Git LFS를 사용하세요:
Bash
git lfs install
git lfs track "*.zip"
git add .gitattributes정리
| 상황 | 해결 |
|---|---|
| 원격에 새 커밋 있음 | git pull --rebase 후 push |
| Protected branch | PR 생성 |
| 브랜치명 불일치 | git push origin 로컬:원격 명시 |
| 대용량 파일 | git rm --cached 후 amend |
protected branch / hook declined 로 거부될 때
! [remote rejected] ... (protected branch hook declined)는 원격 저장소(GitHub 등)의 브랜치 보호 규칙이 직접 push를 막은 것이다. non-fast-forward와 달리 git pull --rebase로는 풀리지 않는다.
- main·master 직접 push 금지 규칙 → 새 브랜치를 만들어 Pull Request로 병합한다.
- 필수 리뷰·상태 검사 미충족 → 리뷰 승인·CI 통과 후 병합.
- 긴급 상황이면 저장소 관리자가 Settings → Branches에서 보호 규칙을 일시 조정(권장하지 않음).
편집 안내 · Editorial Note
이 가이드는 AI 도구를 활용해 초안을 구성하고 사람이 명령어·문맥을 검토해 발행했습니다. 운영체제와 도구 버전에 따라 결과가 달라질 수 있으므로 적용 전 공식 문서를 함께 확인하세요. 오류를 발견하시면 이메일로 제보해 주세요.
관련 공식 문서Git 공식 문서 ↗
질문 & 답변 (Q&A)
이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.