GitHub 저장소 push 권한 변경과 검증 절차

1. 사례와 진단

moosjiny-art/hyperbook 저장소에 대해 현재 인증된 moosjiny 계정의 API 권한은 pull=true, push=false, maintain=false, admin=false였다. 따라서 저장소를 clone하고 읽는 것은 가능하지만 main 브랜치에 push할 수 없다. 로컬 작업은 커밋되어 있으며 커밋 fe57beb가 원격 main보다 한 개 앞서 있지만, 원격 push는 HTTP 403으로 거부됐다.

권한 문제는 Git 설정이나 커밋 문제와 구분해야 한다. 먼저 실제 인증 계정과 저장소 권한을 확인하고, 브랜치 보호 규칙이나 조직 정책이 추가로 적용되는지 확인해야 한다.

2. 가장 직접적인 해결: 저장소 소유자 또는 관리자 초대

저장소 소유자 또는 관리자 권한이 있는 사람이 GitHub 웹에서 다음 절차를 수행한다.

1. moosjiny-art/hyperbook 저장소를 연다.
2. Settings → Collaborators and teams로 이동한다.
3. Add people 또는 협업자 추가를 선택한다.
4. GitHub 사용자 moosjiny를 정확히 선택한다.
5. 권한을 Write로 지정하고 초대를 보낸다.
6. 초대받은 사용자가 이메일 또는 GitHub 알림에서 수락한다.

공개 저장소라도 읽기 권한과 쓰기 권한은 별개다. 단순 코드 수정과 push에는 일반적으로 Write가 충분하다. 저장소 설정 변경이 필요하지 않다면 Maintain이나 Admin을 부여하지 않는 최소 권한 원칙을 지킨다.

3. 조직 저장소인 경우

저장소가 조직 소유이고 팀으로 관리한다면 조직 소유자 또는 저장소 관리자에게 moosjiny를 적절한 팀에 추가하도록 요청한다. 팀의 저장소 권한을 Write로 설정할 수 있다. 조직의 SAML SSO, IP allowlist, 승인된 애플리케이션 정책이 있으면 계정 인증 후 SSO 승인을 별도로 완료해야 한다.

조직 정책으로 외부 협업자, 포크, PAT 또는 SSH 키가 제한될 수 있으므로 권한 추가 후에도 403이 지속되면 조직의 audit log와 저장소의 branch ruleset을 확인한다.

4. 인증 수단 점검

저장소 권한을 부여한 뒤 Git이 올바른 계정으로 인증되는지 확인한다.

gh auth status
gh api user --jq .login
gh api repos/moosjiny-art/hyperbook --jq .permissions

HTTPS를 사용할 때는 GitHub CLI의 credential helper를 사용할 수 있다.

gh auth setup-git
git remote set-url origin https://github.com/moosjiny-art/hyperbook.git
git push origin main

SSH를 사용할 때는 해당 GitHub 계정에 등록된 SSH 키를 사용하고, 호스트 확인 결과가 기대한 계정인지 확인한다.

ssh -T git@github.com
git remote set-url origin git@github.com:moosjiny-art/hyperbook.git
git push origin main

SSH 키나 토큰을 다른 사람과 공유하지 않는다. Fine-grained PAT를 사용해야 한다면 해당 저장소만 대상으로 지정하고 Contents 권한을 필요한 수준으로만 부여하며, 만료일을 설정한다. 토큰을 URL·소스·로그에 넣지 않는다.

5. 브랜치 보호와 pull request 흐름

저장소에 push 권한이 생겨도 main이 보호되어 직접 push가 금지될 수 있다. 이 경우 일반 흐름은 작업 브랜치를 만들고 push한 다음 pull request를 여는 것이다.

git switch -c feature/decision-demo
git push -u origin feature/decision-demo
gh pr create --base main --head feature/decision-demo

보호 규칙이 요구하는 CI 통과, 리뷰 승인, signed commit, linear history를 모두 확인한다. 보호 규칙을 우회하기 위해 관리자 권한을 확대하는 것은 적절하지 않다.

6. 권한을 부여할 수 없을 때의 대안

소유자가 직접 push 권한을 줄 수 없는 경우에는 다음 대안을 사용한다.

• 개인 또는 조직 공간에 저장소를 fork하고 해당 fork에 push한 뒤 원본으로 pull request를 보낸다.
• 변경 패치 또는 커밋 SHA를 전달해 저장소 관리자가 cherry-pick하도록 한다.
• 별도 저장소에 작업을 올리고 원본 관리자가 필요한 커밋을 수동으로 이식한다.

fork와 pull request는 원본 저장소의 직접 쓰기 권한 없이도 검토 가능한 협업 경로다. 단, 비밀정보가 포함된 브랜치나 커밋을 공개 fork로 보내지 않도록 먼저 diff를 점검한다.

7. 안전한 권한 변경 원칙

권한은 작업 목적에 맞는 최소 수준으로 부여한다. 일상적인 웹 파일 수정은 Write, 저장소 운영은 Maintain, 설정·협업자 관리가 필요한 제한된 담당자만 Admin을 사용한다. 초대 링크와 PAT를 메시지나 thesis에 기록하지 않으며, 퇴사·역할 변경 시 즉시 권한과 토큰을 회수한다.

권한 변경 전후에 다음을 점검한다.

1. 저장소 소유자와 대상 계정이 정확한지 확인한다.
2. 공개 저장소인지 비공개 저장소인지 확인한다.
3. branch protection/ruleset, 조직 SSO, IP 제한을 확인한다.
4. .env, API 키, 토큰, 개인 데이터가 diff에 없는지 확인한다.
5. 작은 비파괴 브랜치 push로 권한을 검증한다.
6. 필요하면 테스트 후 브랜치를 삭제한다.

8. 이 사례의 권장 절차

이 사례에서는 moosjiny-art 소유자 또는 관리자가 moosjiny에게 저장소 Write 권한을 부여하고, 초대 수락과 GitHub CLI 재인증을 완료하는 것이 가장 짧은 해결책이다. 이후 현재 로컬 커밋 fe57beb를 main에 push하되, main 보호 규칙이 있으면 feature 브랜치와 pull request를 사용한다. push 후에는 원격 커밋 SHA와 웹 파일 내용을 확인하고, systemd가 해당 저장소 경로를 실행하는지 별도로 점검한다.

결론

403 push 오류는 로컬 Git 문제가 아니라 저장소 권한의 문제다. 소유자가 moosjiny에 최소 권한인 Write를 부여하고, 인증 계정·SSO·브랜치 보호를 차례로 검증하면 해결할 수 있다. 직접 권한 부여가 불가능하면 fork와 pull request가 안전한 대안이며, 어떤 경로에서도 토큰과 비밀정보는 공유하거나 커밋하지 않아야 한다.