GitHub 공개 저장소 clone 인증 요구: HTTPS 오류 확인과 안전한 재시도

어떤 요청이 영향을 받나요?

이번 안내의 대상은 github.com의 공개 저장소이며 모든 플랜에 적용될 수 있습니다. 아래의 ‘영향 없음’은 이번 임시 보호의 적용 대상이 아니라는 뜻입니다. 해당 연결의 모든 오류가 사라진다는 보장은 아닙니다. 근거: GitHub 10월 19일 변경 공지

요청 종류	이번 보호의 적용 여부	진단할 때의 의미
인증하지 않은 HTTPS clone·fetch	일부 요청에 임시 적용 가능	인증 요구 안내가 있는지 확인
인증된 HTTPS Git 작업	영향 없음	실패하면 자격증명 전달·권한 등 별도 점검
SSH Git 작업	영향 없음	SSH 키·네트워크 연결 조건 확인
push	영향 없음	쓰기 권한·브랜치 보호 등 별도 원인 조사
관련 없는 GitHub 웹·API 트래픽	영향 없음	브라우저 접속 성공만으로 Git 인증을 판정하지 않기

공식 발표일은 2026년 10월 19일입니다. 특정 시행 시각이나 보호 해제 시각은 제시되지 않았으므로, ‘몇 시부터 전체 차단’ 또는 ‘몇 분 뒤 자동 복구’로 해석하면 안 됩니다.

먼저 실패한 단계와 실제 메시지를 확인하세요

빌드 마지막 줄의 실패 요약보다 처음 실패한 Git 작업을 찾는 편이 원인 분류에 도움이 됩니다. 메인 저장소 체크아웃이 끝난 뒤 다른 저장소를 가져오는 스크립트가 실패했다면, 두 작업의 URL과 인증 경로를 각각 조사해야 합니다. 아래는 편집부의 진단 순서이며 실제 장애 로그나 재현 결과가 아닙니다.

1. 대상 확인: github.com의 공개 저장소인지, 소유자·저장소 이름이 맞는지 확인합니다.
2. 프로토콜 확인: 실패한 URL이 HTTPS인지 SSH인지 확인합니다. 기존 로컬 저장소의 remote와 CI 설정에 적힌 URL이 다를 수 있습니다.
3. 단계 확인: 메인 clone·fetch인지, 서브모듈·LFS·패키지 설치 단계인지 구분합니다.
4. 오류 보존: 인증을 요구한다는 실제 안내, 발생 시각·시간대, 실행 환경을 기록합니다. 일반적인 인증 실패 한 줄만으로 이번 보호라고 확정하지 않습니다.
5. 전달 경로 확인: 토큰을 등록한 위치와 실패한 Git 명령을 실행하는 프로세스가 같은 인증 설정을 사용하는지 확인합니다.

remote URL은 https://github.com/OWNER/REPOSITORY.git 또는 git@github.com:OWNER/REPOSITORY.git처럼 프로토콜을 구분해 읽습니다. 기존 저장소에서는 git remote -v로 확인할 수 있지만, URL에 자격증명이 들어 있을 수 있으므로 출력은 로컬에서 확인하고 공유본에서는 토큰·사용자 정보 등을 제거하세요. 근거: remote URL 확인·변경 문서

관찰한 상태	다음 확인
비인증 HTTPS clone·fetch에서 인증 요구 안내	아래 환경별 인증 경로로 재시도하고 전후 기록 비교
인증을 구성했는데도 계속 실패	실제 Git 요청의 자격증명 사용 여부·토큰 만료·대상 저장소 권한 확인
SSH 연결 또는 push에서 실패	이번 보호와 분리해 해당 작업의 인증·네트워크·권한 조사
Git 다운로드는 끝났지만 파일 준비가 느림	LFS·체크아웃·설치 단계를 나눠 시간과 오류 확인

마지막 경우에는 Vercel Git LFS 체크아웃 지연 확인 방법을 참고할 수 있습니다. 접근 실패와 파일 준비 속도는 서로 다른 점검 과제입니다.

실행 환경별로 인증을 선택하는 방법

실행 환경	우선 검토할 방식	빠뜨리기 쉬운 확인
개발자 로컬 PC	GitHub CLI·자격증명 관리자 또는 준비된 SSH 인증	브라우저 로그인과 Git 명령의 인증은 별개
GitHub Actions	내장 GITHUB_TOKEN	현재 저장소와 추가로 가져오는 저장소의 범위 구분
다른 CI 시스템	GitHub App installation access token 우선 검토	설치 대상·Contents 권한·만료·Git 단계로의 전달 확인
인증을 구성할 수 없는 작업	보호 해제 후 비인증 재시도	정해진 해제 시간이 없으므로 작업 보류와 실패 처리를 설계

Actions와 다른 CI의 선택은 GitHub 공지의 권장 경로를 따릅니다. 다른 CI에서는 PAT도 사용할 수 있습니다. 로컬 인증 방식은 GitHub 인증 문서를 기준으로 현재 도구와 조직 정책에 맞춰 선택하세요.

로컬 HTTPS: GitHub CLI 로그인 후 Git 연결 확인

GitHub CLI가 설치된 개인 개발 환경이라면 다음과 같이 github.com에 브라우저 방식으로 로그인하고 Git 자격증명 도우미를 연결할 수 있습니다. setup-git은 Git이 CLI를 credential helper로 사용하도록 설정하므로 회사에서 관리하는 기존 인증 설정과의 관계를 먼저 확인하세요. 로그인 명령 · Git 연결 명령

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com

로그인 과정의 자격증명 저장 위치도 확인하세요. CLI는 시스템 자격증명 저장소를 사용하지만 사용할 수 없으면 평문 파일로 저장할 수 있다고 안내합니다. 이미 다른 credential helper를 쓰고 있다면 기존 도구에서 계정·만료 상태를 점검하는 방법도 있습니다.

인증 구성을 마친 뒤 OWNER와 REPOSITORY를 실제 대상으로 바꾸고, 새 clone 또는 기존 저장소 fetch 중 필요한 작업 하나를 실행합니다. 아래는 사용 예시이며 이 글에서 실행한 성공 기록은 아닙니다.

# 새로 복제할 때: 아직 사용하지 않는 로컬 경로 지정
git clone https://github.com/OWNER/REPOSITORY.git ./repo-check

# 이미 복제한 저장소라면: 해당 폴더 안에서 실행
git fetch origin

실패한 clone이 남긴 폴더가 있다면 내용을 먼저 확인하세요. 같은 경로에 다시 clone하다 생긴 디렉터리 오류를 인증 문제로 혼동하거나 작업 파일을 지워서는 안 됩니다. 계정 비밀번호를 반복 입력하는 방식도 해결책이 아닙니다. GitHub는 Git의 비밀번호 인증을 제거했으며 HTTPS에는 지원되는 토큰·자격증명 도우미 등을 사용합니다. 근거: 명령줄 인증 방식

SSH 키가 이미 준비돼 있다면 SSH 경로도 검토할 수 있습니다. 다만 remote 변경만으로 키 등록이나 회사 방화벽 설정까지 완료되지는 않습니다. 조직이 SAML SSO를 사용하면 PAT·SSH 키의 조직 승인 조건도 따로 확인해야 합니다.

GitHub Actions: 토큰은 존재하고, checkout이 사용하나요?

GITHUB_TOKEN은 작업에 자동으로 제공되며, actions/checkout의 기본 token 입력도 github.token입니다. 따라서 기존 checkout에 인증이 이미 구성됐다면 무조건 PAT를 추가하기보다 어느 단계가 실패했는지부터 보세요. 아래는 워크플로가 들어 있는 저장소 하나를 읽는 수동 실행 예시입니다. 근거: 토큰 사용과 최소 권한 · checkout 공식 설정

name: Authenticated checkout check
on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  checkout:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout current repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          token: ${{ github.token }}
          persist-credentials: false
      - name: Record checked-out commit
        run: git rev-parse --verify HEAD

동일한 workflow 예제 다운로드. 파일을 대상 저장소의 .github/workflows/에 추가해 검토한 뒤 사용하세요. 예시는 v7.0.1의 공식 릴리스 커밋으로 고정했습니다. 이 글에서는 원격 Actions를 실행하지 않았습니다.

persist-credentials: false는 checkout 후의 스크립트에 인증을 유지하지 않도록 선택한 설정입니다. 따라서 뒤에서 별도 git fetch를 수행하려면 그 단계의 인증도 따로 설계해야 합니다. 출력되는 HEAD는 가져온 커밋 확인용이며 앱 빌드·테스트 성공을 의미하지 않습니다.

또한 이 토큰의 권한은 워크플로가 있는 저장소에 한정됩니다. 다른 비공개 저장소나 추가 의존성을 가져올 때까지 같은 토큰으로 해결된다고 가정하지 마세요. 공개 저장소를 추가로 가져오는 작업도 실패한 URL과 실제 인증 사용 여부를 개별 확인합니다. 근거: GITHUB_TOKEN의 저장소 범위

다른 CI: App 설치 토큰의 대상·권한·만료 확인

GitHub App 설치 토큰으로 HTTP 기반 Git 접근을 하려면 App에 저장소의 Contents 권한이 필요합니다. 설치 대상과 토큰에 허용된 저장소·권한이 실제 clone 대상에 맞는지 확인하세요. 설치 토큰은 1시간 뒤 만료되므로 오래 대기한 작업이 이전 토큰을 재사용하지 않는지도 봐야 합니다. 근거: 설치 토큰의 Git 접근·권한·유효기간

1. 대상 계정·저장소에 App이 설치돼 있는지 확인하고, 읽기 작업에 필요한 최소 권한을 정합니다.
2. 실행 시 사용할 설치 토큰을 발급하고 CI의 비밀값 전달 기능으로 Git 단계에 연결합니다.
3. Git credential helper 또는 CI의 지원 인증 방식으로 사용하고, remote URL은 토큰이 없는 형태로 유지합니다.
4. 인증 후 같은 대상에 재시도해 종료 코드와 가져온 커밋을 기록합니다.

특히 CI가 소스를 가져온 뒤에야 사용자 스크립트를 실행한다면, 스크립트 내부에서 발급한 토큰은 이미 실패한 최초 체크아웃에 적용되지 않습니다. 이 경우 CI의 소스 연결·체크아웃 설정에서 인증을 구성해야 합니다. 이는 CI 작업 순서를 기준으로 한 점검 방법이며, 제품마다 설정 위치는 다릅니다.

토큰을 URL에 직접 붙여 복사하면 명령 이력·설정 파일·로그에 남을 수 있습니다. 발급 여부만 확인하고 끝내지 말고 실패한 프로세스에 실제로 전달되는지 확인하되, 토큰 원문이나 Authorization 헤더를 진단 자료에 남기지 마세요.

인증할 수 없다면 재시도를 어떻게 운영하나요?

공식 대안은 임시 보호가 해제된 뒤 다시 시도하는 것입니다. 다만 해제 시간이 정해져 있지 않으므로 기다리는 것만으로 완료 시각을 약속할 수는 없습니다. 아래는 무한 반복을 피하기 위한 편집부 운영 권고이며 GitHub가 지정한 재시도 간격이 아닙니다.

• 자동 작업에는 총 시도 횟수·대기 시간의 상한과 실패 후 알림 담당자를 정합니다.
• 재시도 간격을 점차 늘리고 여러 작업이 같은 순간에 몰리지 않도록 분산합니다.
• 저장소·브랜치·커밋 조건을 유지해 재시도하고, 인증 설정 변경 여부를 기록합니다.
• 일정이 중요한 작업은 인증 구성 가능 여부를 먼저 검토하고, 불가능하면 보류 또는 실패 상태를 명확히 남깁니다.

인증 후 성공했다는 결과는 복구 경로를 확인한 자료입니다. 그 사실 하나만으로 최초 실패가 임시 보호 때문이었다고 확정할 수는 없습니다. 반대로 나중에 비인증 요청이 성공해도 같은 환경이 계속 성공한다는 보장은 없습니다. 최초 안내·발생 시각·변경 내용을 함께 남겨야 원인을 좁힐 수 있습니다.

재시도 결과는 이 항목으로 기록하세요

비밀값을 제외한 진단 기록 양식 다운로드. 아래 항목은 채워 넣기 위한 빈 양식이며 장애 로그가 아닙니다. 공개 문의에는 내부 저장소 이름·실행자 정보도 필요한 만큼 가려서 공유하세요.

발생 시각 / 시간대:
실행 환경 / Git 버전 / CI 실행 ID:
대상 호스트 / 공개 여부 / remote 프로토콜:
실패 단계 / 요청한 브랜치 또는 커밋:
실제 오류 메시지(비밀값 제거):
인증 방식 / 대상·권한 확인 여부(토큰 원문 제외):
바꾼 설정 / 재시도 시각 / 종료 코드:
가져온 커밋 / 남은 실패 단계:
판단: 원인 미확인 · 임시 보호 가능성 · 별도 인증/네트워크 문제
다음 확인 / 담당자:

자주 묻는 질문

공개 저장소가 모두 인증 필수로 바뀐 건가요?

아닙니다. 일부 비인증 HTTPS clone·fetch에 임시 적용될 수 있는 보호입니다. 저장소 공개 여부와 요청의 인증 여부를 나눠 확인하세요.

GitHub Actions와 다른 CI는 어떤 인증을 사용하나요?

공식 권장은 Actions의 내장 GITHUB_TOKEN, 다른 CI의 GitHub App 설치 토큰입니다. 다른 CI에서 PAT도 사용할 수 있지만 대상 저장소·권한·만료와 실제 Git 단계로의 전달을 확인해야 합니다.

인증할 수 없는 환경에서는 어떻게 대응하나요?

임시 보호가 해제된 뒤 비인증 상태로 재시도할 수 있습니다. 해제 시각은 공지되지 않았으므로 재시도 상한과 보류·실패 처리를 정하고, 급한 작업은 인증 가능한 경로를 검토하세요.

확인 범위와 업데이트 기록

2026년 10월 21일 GitHub 변경 공지·인증 문서·CLI 매뉴얼·checkout 공식 자료를 대조했습니다. 이 글은 공식 대응 분석이며 임시 보호를 직접 재현하거나 실제 GitHub 인증·clone·fetch·Actions 재시도를 수행한 후기는 아닙니다. 실제 오류 문구와 성공 로그를 만들어 넣지 않았습니다.

공지의 적용 범위·권장 인증 방식이 바뀌거나 검증 가능한 재시도 기록을 확보하면 해당 부분을 갱신합니다. 발표일과 이 글의 검수·발행일은 구분해 표시합니다.