본문 바로가기

직접 만든 소프트웨어, 두 가지 개발 기록

구현 구조와 적용 범위, 확인한 기능과 남은 한계를 함께 기록합니다.

소프트웨어개발

GitHub AI Scan 관리 API 추가: 설정 켜기와 검사 완료는 달라요

by 아빠띠띠뽀 2026. 11. 17.

GitHub의 새 AI Scan REST 기능은 저장소 검사 설정을 관리하는 기능이며, 설정을 켰다는 응답만으로 실제 검사가 완료된 것은 아니에요. 2026년 11월 13일 발표는 기존 AI Scan 관리 엔드포인트에 repository_scan 설정을 추가한 공개 미리보기를 설명합니다.

이 글은 조직의 여러 저장소에 AI Scan을 도입하려는 보안·개발 담당자를 위한 안내입니다. 11월 16일 공식 발표와 현재 REST 참조·개념 문서를 확인했어요. 실제 조직의 정책·권한을 바꾸거나 API 요청과 취약점 검사를 실행한 시험기는 아닙니다.

이번 API의 대상과 지원 범위를 먼저 확인해요

발표가 다루는 경로는 조직 수준과 저장소 수준의 AI Scan 설정 조회·변경입니다. 각각 GET과 PATCH 방식이 있으며 조직 경로는 /orgs/{org}/code-scanning/ai-scan, 저장소 경로는 /repos/{owner}/{repo}/code-scanning/ai-scan입니다. 경로 이름만 보고 검사 실행 명령으로 사용하면 목적이 달라져요.

이번 발표의 조직 소유 저장소 범위에서는 공개 저장소와 GitHub Code Security 또는 GitHub Advanced Security를 갖춘 비공개·내부 저장소의 조건을 구분합니다. GitHub Enterprise Server는 이 발표의 지원 대상이 아니라고 명시돼 있어요. 실제 대상이 어느 호스팅 환경과 저장소 소유 형태에 해당하는지부터 기록할 부분입니다.

현재 개념 문서에는 개인 계정이 소유한 공개 저장소 등 더 넓은 가용성 설명도 있습니다. 그래서 이 조직용 관리 API의 조건을 읽고 개인 계정에서는 모든 AI Scan을 쓸 수 없다고 일반화하지 않겠습니다. 이 글의 실용 범위는 조직 소유 저장소의 정책과 설정 관리에 한정합니다.

또한 개념 문서는 GitHub Copilot 라이선스가 필수는 아니라고 설명합니다. Copilot 사용 여부와 보안 기능의 가용성·청구를 한 확인으로 묶지 않는 편이 좋아요. 제품 이름에 AI가 들어 있다는 이유로 기존 도구의 이용 자격이 그대로 옮겨 온다고 생각하지 말고 현재 저장소에 적용되는 조건을 대조해야 합니다.

저장된 값과 상위 정책을 따로 읽어 보세요

REST 참조는 조직 조회 응답을 조직에 저장된 값으로 설명합니다. 동시에 조직은 기업 정책을 존중한다고 명시해요. 조회 결과에서 한 값을 읽은 사실과 상위 정책까지 허용돼 실제로 사용할 준비가 끝났다는 판단을 구분할 이유입니다. 도입 메모에는 값이 어느 계층에서 관찰됐는지 함께 남겨 주세요.

조직에서 저장소 AI Scan을 꺼 두면 개별 저장소는 이를 켤 수 없습니다. 조직에서 켜면 저장소가 설정을 상속하고 개별적으로 빠질 수 있다고 발표합니다. 한 저장소에서 설정이 다르게 보인다고 곧바로 API가 실패했다고 보기보다, 조직 기본값과 개별 제외 상태를 나누어 확인해야 합니다.

pr_scan은 풀 리퀘스트에 대한 검사 설정이고 repository_scan은 저장소 전체 AI Scan 설정입니다. 이름이 비슷하지만 확인하려는 작업이 다릅니다. 기존 풀 리퀘스트 검토를 관리하려는지, 기본 브랜치의 백로그 검사를 준비하려는지부터 정하면 요청에서 무엇을 바꿀지 좁힐 수 있어요.

가령 조직은 저장소 검사를 켰지만 특정 저장소가 개별 제외 상태라고 해 볼게요. 조직 조회 화면만 기록해서는 그 저장소의 준비 상태를 설명하기 어렵습니다. 반대로 저장소 값만 보고 조직 전체 도입이 끝났다고 할 수도 없어요. 이는 정책 상속을 읽기 위한 가상 사례이며 실제 계정에서 관찰한 설정은 아닙니다.

실무에서는 변경할 대상 목록과 현재 두 설정값, 상위 정책을 확인한 담당자를 함께 적어 보는 방식을 제안합니다. 값의 출처가 다르면 기록에서도 다른 칸을 쓰는 것입니다. 문서의 지원 조건과 실제 계정에서 본 사실을 구분하면 나중에 도입 범위를 설명하기 수월해집니다.

조회 권한과 변경 권한은 같은 준비가 아니에요

공식 발표는 조직 소유자와 보안 관리자가 조직 설정을 관리하고, 저장소 관리자가 개별 저장소를 제외할 수 있다고 설명합니다. 조직 안에서 코드를 읽는다는 사실만으로 모든 설정 변경 권한이 있는 것은 아니에요. 요청을 담당할 역할과 허용된 작업 범위를 먼저 확인해야 합니다.

현재 REST 참조에서 세분화된 토큰의 조직 설정 조회에는 조직의 Administration 읽기 권한, 변경에는 쓰기 권한을 요구합니다. 두 동작을 같은 권한으로 설명하지 않겠습니다. 문서는 GitHub App 토큰과 세분화된 개인용 토큰 등 지원 인증 형식도 나누어 안내하므로 실제 사용하는 형식에 해당하는 조건을 읽어야 합니다.

이 글은 필요한 권한을 넓히거나 새 토큰을 만들라는 실행 지시가 아닙니다. 이미 승인된 인증과 조직 절차 안에서 누가 어떤 작업을 수행하는지 정리하는 안내예요. 비밀값을 원고·작업 메모에 붙여 넣거나 거절된 정책을 피해 더 강한 계정을 사용하는 방식으로 진행하지 않아야 합니다.

현재 확인한 REST 페이지는 API 버전 2026-03-10을 표시합니다. 실제 구현에서는 사용하는 API 버전과 대상 조직·저장소를 함께 남겨 보세요. 문서를 읽은 날짜와 API 버전을 같은 날짜로 적지 않는 것도 중요합니다. 이 글은 그 버전의 참조를 확인했지만 독자의 요청이나 환경을 직접 시험하지 않았습니다.

두 설정을 함께 바꾼 요청이 거절되면 추측하지 마세요

발표는 pr_scan과 repository_scan을 한 요청에 함께 바꿀 수 있다고 설명합니다. 이때 어느 한 변경이 막히면 422를 반환하고 두 설정 모두 바뀌지 않는다고 명시해요. 한 필드만 성공했을 것이라고 읽거나, 원하는 값이 들어갔다고 가정한 채 다음 절차로 넘어가면 관찰과 기록이 어긋납니다.

기업 정책이 AI Scan을 허용하지 않으면 켜려는 요청이 422를 반환한다는 사례도 나옵니다. 다만 모든 422를 같은 정책 원인이라고 단정해서는 안 됩니다. REST 참조는 변경 엔드포인트의 422에 유효성 검사 실패 등의 설명도 제시합니다. 실제 응답의 내용과 요청 조건을 함께 읽을 문제입니다.

다른 응답 코드도 맥락이 있습니다. 공식 참조에는 403 Forbidden과 404 Resource not found가 나열돼 있어요. 이 코드만 보고 계정이 로그아웃됐거나 모든 저장소가 없다고 확대 해석하지 마세요. 대상 식별자·가시성·호출자 역할과 문서에 나온 권한을 확인하는 출발점으로 읽으면 됩니다.

변경 전에 저장한 값과 승인된 요청의 목적을 보존하고, 변경 뒤에는 실제 값을 다시 조회해 대조하는 순서를 제안합니다. 응답이 불명확할 때 곧바로 같은 변경을 다시 보내기보다 현재 값을 먼저 확인하는 방식이에요. 재조회는 어느 설정이 실제로 관찰됐는지 판단할 근거를 남기는 과정입니다.

가상 도입 기록에는 요청 시각, 대상, 변경하려던 두 필드, 응답 상태와 메시지, 이후 확인한 값이 들어갈 수 있습니다. 인증 헤더나 토큰 원문은 남기지 마세요. 거절 원인이 정책이라면 담당 절차로 확인할 질문을 남겨야 하며, 요청을 쪼개서 제한을 피하는 방법을 찾는 문제가 아닙니다.

실제 검사는 별도의 실행과 검토가 필요해요

이번 발표는 설정을 켜도 저장소 검사가 시작되지 않는다고 분명히 적습니다. 쓰기 권한이 있는 사용자가 필요할 때 검사를 실행하고 각 검사는 Code Security AI credits를 사용합니다. 설정 변경 수와 실제 실행 수, 청구 사용량을 같은 숫자로 취급하지 않는 편이 좋습니다.

현재 개념 문서에서 저장소 AI Scan은 기본 브랜치를 대상으로 수동 실행합니다. CodeQL과 독립적으로 동작하고 결과는 기존 코드 검사 경고 목록에서 관리합니다. 예약 검사나 푸시 때 자동 검사까지 이 설정 API가 제공하는 것으로 설명해서는 안 돼요. 지원 여부는 실제 검사 방식의 문서를 별도로 읽어야 합니다.

또한 에이전트는 시간 예산 안에서 분석할 코드를 선택하며 모든 파일을 완전히 읽거나 모든 취약성을 발견한다고 보장하지 않습니다. 경고가 없다는 결과도 서비스 전체의 안전 증명은 아니에요. AI가 만든 발견 사항은 부정확할 수 있으므로 해결 방법을 정하기 전에 사람이 각각 검토할 필요가 있습니다.

그래서 준비 상태, 실행 상태, 결과 검토 상태를 구분해 보세요. 먼저 대상에서 기능을 사용할 조건이 맞는지 읽고, 실제 실행 기록이 있는지 확인하며, 마지막으로 경고를 검토한 범위와 남은 질문을 적는 것입니다. 단순한 enabled 한 칸에는 이런 다른 단계의 근거가 담기지 않습니다.

크레딧과 예산도 실제 청구 계정의 현재 조건으로 확인해야 합니다. 이 글은 사용량이나 보안 개선 효과를 측정하지 않았어요. 도입 전에 어떤 계정이 비용을 부담하고 누가 사용 범위를 승인하는지 정리하는 것이 목적입니다. 설정이 자동화됐다는 사실만으로 무제한 실행이나 예산 밖 사용이 허용되는 것은 아닙니다.

작게 도입하고 무엇이 끝났는지 정확히 남겨요

처음에는 조직이 승인한 작은 저장소 목록에서 정책과 설정 확인 순서를 정해 보세요. 현재 값과 기대 값을 비교하고, 실제 검사를 할 담당자·예산·시점을 따로 남기는 방식입니다. 한 저장소에서 본 결과를 모든 조직과 저장소의 도입 완료로 넓히지 않는 편이 좋습니다.

원래 설정으로 돌아갈 계획도 변경 전에 적어 두면 도움이 됩니다. 어떤 두 값을 보존했고 복구 변경을 누가 승인하는지 정하는 것이에요. 설정을 되돌렸다는 관찰을 이미 수행한 검사 사용량이나 경고 처리까지 되돌아갔다는 증거로 쓰지 않아야 합니다. 서로 다른 상태를 별개로 확인할 문제입니다.

자주 묻는 질문도 정리해 볼게요. enabled면 검사가 끝났나요? 실제 실행·완료 기록이 필요합니다. 422면 두 필드 중 하나는 바뀌었나요? 발표의 결합 변경 거절 조건과 현재 값을 다시 대조해야 해요. 경고가 없으면 안전한가요? 문서가 설명하는 분석 범위와 사람 검토의 한계를 함께 봐야 합니다.

이번 기능은 여러 저장소의 설정을 일관되게 관리할 통로를 추가한 변화입니다. 도입 결과에는 설정을 읽고 바꾼 사실, 실제 검사 수행, 경고 검토를 각각 적어 보세요. 자동화의 성공을 더 크게 표현하는 것보다 담당자가 어떤 단계의 근거를 가진 것인지 바로 알 수 있는 기록이 운영에 도움이 됩니다.

자료 확인일은 2026년 11월 16일입니다. 공식 발표와 현재 문서로 확인한 범위를 정리했으며 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경 조건은 담당자가 다시 확인해 주세요.

함께 읽어 볼 글: Actions 로그의 시크릿 검사와 경고 대응 범위를 나누는 글. 이번 글과 적용 질문이 어떻게 다른지 함께 살펴보세요.

설정 스위치와 닫힌 코드 폴더, 별도 돋보기와 빈 검토 노트를 나누어 놓은 개념 그림
설정 변경과 실제 검사·결과 검토를 구분하는 개념 이미지입니다. 실제 취약점 진단이나 보안 보장 결과를 나타내지 않습니다.