GitHub 웹훅의 새 IP 범위를 수신 허용목록에 반영하는 일과, 들어온 요청의 서명을 검증하는 일은 따로 확인해야 합니다. 2026년 10월 29일 공지는 정적 허용목록을 관리하는 운영자에게 영향을 줄 수 있는 변경입니다. 다만 최근 배포 알림이 오지 않았다는 사실만으로 이 변경을 장애 원인으로 확정하지는 마세요.
GitHub의 웹훅 IP 추가 공지는 Meta API의 hooks 항목에 범위를 추가했다고 알립니다. 정적 목록을 사용한다면 기존 범위와 함께 추가하고, Meta API로 목록을 계속 동기화하고 있다면 이번 추가 때문에 별도 변경할 필요는 없다는 안내예요. github.com의 모든 플랜에 적용된다고 명시하며 Enterprise Cloud도 포함합니다.
누락된 알림을 보면 어느 지점부터 확인할까요?
웹훅은 이벤트가 생겼을 때 정해 둔 주소로 보내는 요청입니다. 운영자가 확인하려는 것은 보통 ‘내 서버가 요청을 받았는가’와 ‘그 요청으로 할 일을 처리했는가’일 거예요. 그런데 두 질문을 같은 것으로 읽으면 수신 문제와 처리 문제를 뒤섞기 쉽습니다. 이번 글에서는 관찰한 지점을 차례로 나누는 자체 점검 메모를 제안합니다.
먼저 실제로 누락됐다고 생각한 이벤트와 확인 시간을 적어 보세요. 그다음 GitHub 쪽의 전달 기록, 네트워크 경계에서 읽을 수 있는 기록, 수신 애플리케이션에서 확인한 기록을 구분합니다. 접근할 권한이 없는 로그는 읽었다고 적지 말고 담당자에게 확인할 항목으로 남겨 주세요. 이 목록은 특정 환경의 장애를 진단한 결과가 아닙니다.
| 관찰한 곳 | 확인할 질문 |
| 전달을 시작한 쪽 | 어떤 이벤트의 어떤 전달을 살펴보고 있나요? |
| 네트워크 경계 | 그 전달이 수신 허용 정책과 관련해 어떻게 처리됐는지 읽을 근거가 있나요? |
| 수신 프로그램 | 요청을 받은 기록과 검증·응답 기록이 연결되나요? |
| 후속 작업 | 받은 요청으로 시작하려던 처리가 실제로 진행됐나요? |
예를 들어 전달 기록에는 실패가 있고 앱에는 관련 요청이 보이지 않는다고 합시다. 여기서 바로 애플리케이션 코드를 고치기보다 두 기록 사이에 무엇을 아직 확인하지 못했는지 적을 수 있습니다. 반대로 앱에서 요청을 받았지만 후속 작업이 없었다면 다른 질문이 남겠죠. 어느 경우도 이 예시만으로 실제 원인을 단정할 수는 없습니다.
공지의 세 범위를 현재 전체 목록으로 사용하지 마세요
10월 29일 공지에 추가된 CIDR 표기는 9.234.98.160/28, 9.234.98.176/28, 9.234.106.48/28입니다. 이것은 해당 공지의 추가 범위이지 GitHub 웹훅의 전체 최신 목록이 아닙니다. 기존 범위를 지우고 이 세 항목만 남기라는 뜻으로 읽으면 안 되겠죠. 현재 값을 확인하는 경로는 Meta API입니다.
Meta API 공식 문서도 문서에 표시된 응답은 예시이며 최신 값은 API에 직접 질의해야 한다고 명시합니다. 문서의 예시 주소를 복사해 운영 정책에 넣는 일을 피해야 하는 이유예요. 메타 정보에는 여러 서비스의 주소 항목이 있으므로 웹훅을 살펴볼 때 어떤 항목을 읽는지도 확인해 주세요.
조회 예시는 아래와 같습니다. macOS·Linux 등에서 curl을 사용할 수 있고 인터넷의 해당 공개 API로 나갈 수 있다는 전제의 읽기 전용 요청입니다. 토큰을 넣거나 운영 서버의 수신 정책을 바꾸는 명령이 아닙니다. 이 글에서는 실제로 실행하지 않았으며, 응답값이나 조회 성공 화면을 만들어 제시하지 않습니다.
curl --fail --silent --show-error \
https://api.github.com/meta문서는 공개 자원만 요청하는 경우 인증 없이 이 엔드포인트를 사용할 수 있다고 설명합니다. 자신의 조직에서 허용하는 조회 방식은 별도로 확인할 일입니다. 조회가 실패했다면 실제 오류를 읽고 연결 조건을 확인하세요. 작동시키기 위해 인증 정보를 붙이거나 네트워크 보호를 해제하라는 절차는 이 글에 없습니다.
조회 결과를 비교할 때는 가져온 시간과 참고한 항목을 함께 남겨 보세요. 지금 읽은 값과 지난 공지의 변경 목록, 현재 적용된 수신 정책이 각각 다른 자료라는 점을 유지하는 겁니다. 공식 출처를 열어 봤다는 사실만으로 운영 설정에도 반영됐다고 기록하지 않는 것이 좋겠습니다.
정적 목록과 자동 동기화는 무엇을 따로 확인할까요?
정적 목록을 관리한다면 먼저 현재 정책의 소유자와 변경 절차를 확인해 보세요. 공지가 안내한 범위를 검토하더라도 기존 정책을 보존하고 변경 전후를 비교할 수 있어야 합니다. 이 글은 특정 방화벽 제품의 설정 명령을 제공하거나 현재 정책을 승인하지 않습니다. 자신의 서비스와 담당자가 정한 절차에 맞춰 검토할 일입니다.
자동 동기화를 사용한다면 ‘자동’이라는 이름보다 실제로 어떤 자료를 가져오고 언제 반영됐는지 확인할 근거를 살펴보세요. 예를 들어 동기화 결과를 읽을 수 있는 담당자에게 최근 실행 시점과 참조 항목을 물어볼 수 있습니다. 공지의 ‘별도 변경이 필요 없다’는 설명과 우리 동기화 작업이 실제로 성공했다는 관찰은 다른 사실입니다.
| 관리 방식 | 현재 상태를 대조할 자료 |
| 정적 허용목록 | 현재 정책, 공지의 추가 범위, 최신 Meta 조회값, 변경을 검토할 담당자. |
| Meta API 동기화 | 동기화가 참조하는 항목, 최근 실행과 반영을 확인할 수 있는 기록. |
| 방식 미확인 | 관리 주체와 실제 설정을 먼저 확인하고, 확인하지 못한 부분은 비워 두기. |
검토안에는 원래 정책으로 돌아가는 방법도 담당자에게 확인해 보세요. 원인을 아직 모르는 상태에서 여러 설정을 한꺼번에 바꾸면 어떤 변경이 어떤 결과와 연결됐는지 설명하기 어려워질 수 있습니다. 여기서는 하나의 변경을 검토할 때 원본과 이유, 실제 확인 결과를 같이 남기는 방식을 제안합니다.
IP 허용 이후에도 요청 서명을 검증해야 해요
전달 서명 검증 문서는 요청을 더 처리하기 전에 서명을 검증해 보낸 주체와 변조 여부를 확인하도록 안내합니다. GitHub는 웹훅 시크릿과 본문으로 HMAC 서명을 만들고 X-Hub-Signature-256 헤더로 전달합니다. 수신 쪽은 같은 시크릿으로 계산한 값과 비교합니다. IP 목록 확인이 이 절차를 대신한다고 설명하지 않습니다.
문서는 UTF-8 처리와 상수 시간 비교 등 구현상 주의점도 제시합니다. 시크릿을 코드에 하드코딩하거나 저장소에 올리지 말라는 안내도 함께 있습니다. 이 글은 시크릿 값이나 실제 요청 본문을 공개하라는 뜻이 아닙니다. 필요한 검증이 구현돼 있는지 확인할 담당자와 문서를 연결하자는 취지예요.
문서의 샘플과 운영 환경의 성공을 구분하는 것도 중요합니다. 샘플 값으로 동작을 이해하는 일과 실제 수신 프로그램이 받은 원문을 올바르게 검증하는 일은 확인 범위가 다릅니다. 프록시나 프레임워크를 포함한 자신의 구성에서 어떤 본문이 검증에 전달되는지는 해당 구현을 아는 담당자가 확인해야 합니다.
자체 검토 질문으로는 ‘서명 검증을 어디서 수행하는가’, ‘실패했을 때 어떤 상태를 남기는가’, ‘시크릿을 드러내지 않고 무엇으로 결과를 확인할 수 있는가’를 남겨 볼 수 있어요. 이 질문만으로 보안 검토가 끝나지는 않습니다. 실제 코드와 운영 조건에 맞는 검증 자료를 확인하는 출발점입니다.
받았다는 응답과 후속 처리 완료도 나누어 봐요
웹훅 권장 사항은 수신 후 10초 이내에 2XX 응답을 보내도록 안내합니다. 그보다 오래 걸리면 GitHub가 연결을 종료하고 전달 실패로 본다는 설명입니다. 오래 걸리는 일은 큐를 이용해 비동기적으로 처리하는 방식을 검토할 수 있다고 제시합니다.
같은 문서는 이벤트 종류와 action을 확인하고, X-GitHub-Delivery로 전달을 식별하는 방법을 설명합니다. 재전달에서도 이 헤더 값이 원래 전달과 같다는 점도 명시해요. 재시도와 별개 이벤트를 구분할 때 참고할 조건입니다. 다만 식별자 하나를 확인했다는 사실만으로 자신의 프로그램에 중복 처리 방지가 완성됐다고 판단할 수는 없습니다.
운영 메모에는 ‘수신 응답’, ‘큐나 후속 작업의 상태’, ‘사용자가 기대한 결과’를 다른 칸에 적어 보세요. 예를 들어 수신 응답은 확인했지만 배포 결과는 확인하지 못했다면 그 범위를 그대로 남기는 겁니다. 응답 코드 하나로 업무 전체의 성공을 표현하지 않으려는 자체 정리 방식입니다.
재전달이 필요하다면 먼저 이전 요청이 어떤 단계까지 처리됐는지 확인할 담당자에게 연결하세요. 실제 상태를 모른 채 여러 번 보내어 원하는 결과가 나오는지 보는 방법을 기본 대응으로 삼지 않는 편이 좋겠습니다. 문서가 제공하는 전달 관리 기능과 자신의 서비스가 감당해야 하는 후속 처리를 함께 검토할 일입니다.
확인 결과를 전달할 때는 이렇게 적어 보세요
‘공지의 IP를 넣었습니다’라는 보고만으로는 어떤 환경을 언제 확인했는지 알기 어렵습니다. 대신 참고한 공지 날짜, 현재 값을 조회한 시각, 실제 적용 정책의 확인 범위, 다음 검토가 필요한 항목을 함께 적어 보세요. 운영 값을 채운 실제 장애 보고가 아닌, 기록 형식의 제안입니다.
가상의 인계 문장으로는 ‘전달 기록을 확인했지만 네트워크 경계의 처리 결과는 담당자 확인이 남았습니다. 10월 29일 추가 공지와 현재 정책을 대조할 예정이며, 앱의 서명 검증 상태는 별도로 검토하겠습니다’처럼 쓸 수 있습니다. 이미 확인한 일과 앞으로 할 일을 분리하면 같은 화면을 반복 확인하는 혼선을 줄이는 데 쓰기 좋겠습니다.
반대로 설정을 변경한 뒤 전달이 성공했더라도 원인에 관한 표현은 확인한 근거에 맞춰 선택하세요. 다른 조건을 함께 바꿨는지, 이전 실패 기록과 같은 이벤트를 보고 있는지, 후속 처리는 실제로 확인했는지가 남습니다. 한 번의 성공을 전체 알림 경로의 안정성이나 모든 요청의 진위 증명으로 확대하지 않습니다.
자주 묻는 질문과 이번 확인 범위
공지에 적힌 IP만 허용하면 되나요? 공지는 추가 범위를 말합니다. 최신 전체 목록은 Meta API에서 확인하라는 공식 안내와 자신의 관리 정책을 함께 대조하세요. 문서의 예시 응답도 실제 값으로 사용하면 안 됩니다.
현재 허용목록이 자동이면 확인할 일이 전혀 없나요? 이번 추가에 대한 별도 변경이 필요 없다는 공지와, 자신의 동기화 상태를 읽는 일은 구분합니다. 확인하지 못한 상태를 성공으로 채워 넣지 않으면 됩니다.
이 글이 실제 장애를 해결한 기록인가요? 아닙니다. 2026년 11월 4일에 공식 변경 공지·Meta API·서명 검증·권장 사항을 대조한 안내입니다. API 요청 실행, 방화벽 변경, 실제 웹훅 수신이나 재전달 시험은 하지 않았습니다. 발행일인 11월 5일의 전체 IP 목록이나 특정 서비스 상태를 확정하지 않습니다.
API 조회에서 주소 이동 응답을 읽는 방법이 필요하다면 curl의 Location과 최종 URL 확인 안내를 참고할 수 있습니다. 주소 이동 확인만으로 웹훅 수신·서명 검증이 끝나는 것은 아닙니다.
'소프트웨어개발' 카테고리의 다른 글
| Copilot 보안 확장 미리보기: Fix를 눌러도 경고가 바로 닫히지 않는 이유 (0) | 2026.11.05 |
|---|---|
| JetBrains Air에 Copilot 지원: 로컬·클라우드와 구독 비용을 어떻게 고를까요? (0) | 2026.11.05 |
| GitHub pull_request_target 기본 차단 예고: 12월 일정과 11월 시험 구간 확인 (0) | 2026.11.04 |
