코드 품질 문제가 기본 브랜치에 유입되는 것을 방지하기

Introduction

이 자습서에서는 첫 번째 댓글부터 병합까지, 하나의 풀 리퀘스트가 Code Quality의 분석을 거치는 과정을 따라가 봅니다. 다음 내용을 배웁니다.

풀 리퀘스트의 Code Quality 댓글을 읽고 두 가지 유형의 지적 사항을 구분하는 방법입니다.
찾기의 심각도 레이블을 사용하여 수정할 항목, 해제할 항목 및 순서를 결정하는 방법입니다.
끌어오기 요청에서 선택한 항목이 리포지토리의 점수, 백로그 및 병합 게이트를 구성하는 방식입니다.

마지막에는 예제 풀 리퀘스트에서 병합을 막는 모든 지적 사항을 해결하고, 문제없이 통과한 Code Quality 체크와 함께 이를 병합하게 되며, 각 선택을 왜 했는지도 이해하게 될 것입니다.

이것은 단계별 안내이므로 속도보다 이해를 우선합니다. 자동 수정을 커밋하거나 탐지 결과를 무시하는 방법에 대한 기본 단계는 관련 방법 문서 끌어오기 요청에서 코드 품질 결과 수정를 참조하세요.

시작하기 전에

Code Quality 은 사용자가 참가하는 리포지토리에서 사용하도록 설정됩니다. GitHub Code Quality 사용을(를) 참조하세요.
리포지토리는 규칙 기반 결과 및 점수가 생성되도록 지원 CodeQL 되는 언어를 사용합니다. 지원되는 언어 목록은 GitHub 코드 품질을 참조하세요.
기본 브랜치를 대상으로 하며 심사할 Code Quality 지적 사항이 하나 이상 있는 풀 리퀘스트가 열려 있습니다. 끌어오기 요청이 준비되지 않은 경우 아래 예제를 따를 수 있습니다.

이 자습서 전반에 걸쳐 계속 사용할 예시로, 일부 코드를 리팩터링하는 풀 리퀘스트가 그 상태 그대로 병합되면 기본 브랜치에 몇 가지 코드 품질 문제를 초래하는 상황을 사용하겠습니다. Code Quality 검사가 풀 리퀘스트에서 자동으로 실행되었으며, 여러 건의 발견 사항을 댓글로 보고했습니다.

끌어오기 요청 단계에서 해결되지 않는 모든 발견은 리포지토리의 백로그에서 작업 항목이 되며 기술 부채는 지금 해결하는 것보다 나중에 상환하는 데 비용이 더 많이 드는 경우가 많습니다. 현재 풀 리퀘스트가 열려 있는 지금은 코드의 맥락과 의도가 아직도 머릿속에 생생하게 남아 있어 각 지적 사항과 그 자동 수정을 더 빠르게 평가하고, 적용하거나, 확신을 가지고 무시할 수 있습니다.

끌어오기 요청 단계에서 결과를 해결한다는 것은 팀이 기능 작업에 대한 수정 작업을 심사하는 데 더 적은 시간을 소비하고 백로그를 소실하기 위해 추가 끌어오기 요청의 오버헤드를 방지한다는 것을 의미합니다.

1단계: 끌어오기 요청에 대한 설명 찾기 Code Quality

끌어오기 요청을 Code Quality 열면 두 가지 유형의 분석을 실행하고 결과를 메모로 게시합니다. 풀 리퀘스트의 변경된 파일 탭을 열고 각 댓글을 누가 남겼는지 확인하세요. 작성자를 보면 그것이 어떤 유형의 지적 사항인지 알 수 있습니다.

규칙 기반 결과는**github-code-quality[bot]** 에 의해 게시됩니다. Code Quality는 CodeQL를 사용해 변경 사항을 규칙 집합을 기준으로 검사하며, 각 코멘트에는 제안된 자동 수정안이 포함됩니다.
AI 기반의 연구 결과는 .에 의해 Copilot 게시됩니다. 조직에 Copilot 라이선스가 있고 엔터프라이즈 Copilot 코드 검토 에 AI 기능이 사용하도록 설정된 경우 규칙 기반 분석에서 놓칠 수 있는 품질 문제를 찾습니다. 이러한 주석에는 자동 수정 제안도 포함됩니다.

이 예제에서는 github-code-quality[bot]에서 나온 세 개의 코멘트를 살펴보겠습니다. 따라서 이는 규칙 기반 탐지 결과입니다. 자신의 풀 리퀘스트에서 두 유형이 모두 표시될 수 있습니다. 계속 진행하기 전에 어느 것이 어느 유형인지 확인하세요. 심각도 레이블(2단계)은 규칙 기반 주석에만 적용되기 때문입니다.

2단계: 심각도 레이블을 읽어 중요한 사항 결정

모든 규칙 기반 찾기는 github-code-quality[bot] 심각도 레이블(오류, 경고 또는 참고)을 전달합니다. 댓글 중 하나에서 레이블을 찾아 이 표와 대조해 확인하세요.

| 심각도 | Definition | |-----------|--------------------| | Error | 버그, 오류 또는 주요 유지 관리 위험의 원인이 될 가능성이 높은 심각도 문제를 나타냅니다. | | 경고 | 코드 품질 또는 안정성에 영향을 미칠 수 있지만 즉시 중요하지는 않은 보통 심각도 문제를 나타냅니다. | | 참고 | 심각도가 낮은 문제, 사소한 개선 또는 권장 사항을 나타냅니다. 이러한 결과는 지속적인 코드 상태 및 유지 관리에 유용합니다. |

레이블이 한 번에 두 가지 작업을 수행합니다.

먼저 해결해야 할 사항을 알려줍니다. 심각도는 일반적인 코드에서 규칙의 예상된 영향을 반영합니다. 이 예제에서는 우선 오류부터 시작하고, 그다음 경고를 처리하며, 참고는 선택적인 마무리로 간주합니다.
병합할 수 있는지 여부를 결정할 수 있습니다. 리포지토리 관리자 또는 조직 소유자는 병합 게이트로 구성할 Code Quality 수 있습니다. 예를 들어 병합 임계값이 "경고 이상"인 경우 병합하기 전에 모든 경고및오류 수준 찾기를 수정하거나 해제해야 합니다(참고 결과에서는 병합을 방해하지 않음). 마찬가지로, 더 엄격한 임계값을 사용하려면 병합하기 전에 모든 결과를 해결해야 할 수 있습니다.

게이트가 적용되는지 확인하려면 끌어오기 요청의 맨 아래에 있는 검사 섹션으로 스크롤합니다. 변경 내용이 필요한 임계값 아래로 떨어지면 병합 블록 배너가 표시됩니다. "병합이 차단됨: 코드 품질 결과가 검색되었습니다."

끌어오기 요청의 체크 섹션에 있는 병합 블록 배너의 스크린샷

이 예제에서 게이트는 "경고 이상"으로 설정되므로 배너가 있습니다. 오류 및 경고 가 병합을 차단하고 메모 가 없습니다. 그러면 이 풀 리퀘스트를 병합하기 전에 해결해야 하는 사항이 무엇인지 알 수 있습니다.

병합 블록 배너가 심각도 수준을 지정하지 않는 경우 끌어오기 요청을 병합하려면 모든 결과를 지워야 합니다.

3단계: 각 발견 사항 해결

모든 발견에 대해 코드에 적용되는지 여부와 코드에 적용되는 경우 수정 방법을 결정합니다. 그러면 세 가지 조치 중 하나를 취하게 됩니다.

Assessment	권장 작업	비고
발견은 합법적이며 제안된 수정 사항이 올바로 보입니다.
자동 수정 제안 적용
커밋 제안을 클릭해도 AI credits이(가) 소모되지 않으며, 규칙 기반 자동 수정에는 Copilot 라이선스가 필요하지 않습니다.
발견은 실제이지만 한 번에 여러 가지를 수정하려고 하거나 제안된 수정 사항을 조정해야 합니다.
**
Copilot에 위임**—댓글에 `@copilot`를 멘션하여 작업을 클라우드 에이전트에 넘기세요.
👀으로 Copilot에 반응하고, 새 에이전트 세션을 시작한 다음 필요한 수정 사항을 풀 리퀘스트 브랜치에 푸시합니다.
Copilot 라이선스가 필요하며 AI credits을 사용합니다.
예를 들어 테스트 코드이거나, 의도적인 패턴이거나, 또는 오탐인 경우에는 이 탐지 결과가 적용되지 않습니다.
찾기 해제를 클릭하고 이유를 입력합니다.	끌어오기 요청을 병합할 수 있지만 검색 결과는 리포지토리 백로그 및 이후 끌어오기 요청에 표시됩니다.

심각도 순으로 자신의 풀 리퀘스트에 연습한 내용을 적용하세요.

이 예제에서는 다음을 수행합니다.

오류 수준 및 경고 수준의 결과는 실제 버그이며, 제안된 자동 수정도 합리적으로 보여 자동 수정 제안을 적용합니다. 발견 사항은 해결되면 차단 건수에서 제외됩니다.
메모 수준 찾기는 인접한 테스트 도우미의 사소한 패턴에 플래그를 지정합니다. 의도적인 것이므로 "테스트에 사용됨"과 같은 이유로 해제합니다.
몇 가지 추가 참고 수준의 발견 사항이 있습니다. 각 자동 수정 제안을 하나씩 처리하는 대신 다음과 같이 설명합니다. "@copilot, 남아 있는 모든 Note 수준의 지적 사항을 수정하세요" 리포지토리의 Agents 탭에서 Copilot의 진행 상황을 추적하고, 준비되면 풀 리퀘스트에 푸시한 커밋을 검토합니다.

4단계: 끌어오기 요청이 차단 해제되어 있는지 확인(선택 사항)

차단하는 결과가 있는 경우, 관련 결과를 수정하거나 무시한 후 끌어오기 요청 하단의 검사 섹션으로 돌아가세요.

이 예제에서는 오류 및 경고 결과를 확인하면 병합 블록 배너가 사라집니다. 이제 풀 리퀘스트를 병합할 수 있는 상태입니다.

배너가 여전히 표시되어 있다면, 차단 수준 이상의 심각도를 가진 문제가 아직 열려 있다는 의미입니다.

5단계: Copilot의 AI 기반 발견 사항 해결하기

조직에 Copilot 라이선스가 있고 엔터프라이즈에 AI 기능이 사용하도록 설정된 경우 Copilot이(가) 게시한 댓글도 표시됩니다. 이는 1단계에서 소개된 AI 기반 분석 결과이며, Copilot 코드 검토가 아니라 github-code-quality[bot]에서 나온 것입니다.

규칙 기반 탐지 결과는 변경 내용을 고정된 CodeQL 규칙 집합과 대조하는 반면, Copilot 코드 검토 코드의 의도를 추론합니다. 특정 규칙에 매핑되지 않는 품질 문제를 catch하므로 이를 대체하는 대신 규칙 기반 주석을 보완하는 데 유용합니다.

이러한 결과는 "오류", "경고" 또는 "참고"의 심각도 레이블을 전달하지 않습니다. 2단계에서 본 병합 게이트는 규칙 기반 결과의 심각도만 계산하므로 AI 기반 조사 결과는 끌어오기 요청을 자체에서 차단하지 않습니다. 그렇다고 해서 선택 사항이 되는 것은 아닙니다. 컨텍스트에서 문제를 해결하는 것은 여전히 품질 문제를 기본 분기에서 벗어나게 하는 최적의 장소입니다.

3단계에서 사용한 것과 동일한 세 가지 선택 항목을 사용하여 AI 기반 찾기를 해결합니다.

자동 수정 제안을 적용하세요. 각 주석에는 제안된 수정 사항이 포함됩니다. 현재 상태가 올바르면 제안 제출을 클릭합니다. 자동 수정을 적용해도 GitHub AI Credits를 소모하지 않습니다.
Copilot에게 위임—댓글에서 @copilot을 멘션하여 작업을 클라우드 에이전트에 넘기세요. Copilot는 👀에 반응하여 새 에이전트 세션을 시작하고 필요한 수정 사항을 풀 리퀘스트의 브랜치에 푸시합니다. 이 옵션을 사용하려면 Copilot 라이선스가 필요하며, GitHub AI Credits를 사용합니다.
주석을 해결합니다. 코드에 적용되지 않는 경우 해결을 클릭합니다.

이것이 코드 건전성의 다른 측면과 어떻게 관련되는지

방금 처리한 풀 리퀘스트는 더 큰 그림의 일부입니다.

점수. 리포지토리의 안정성 및 유지 관리 효율성 점수는 기본 분기의 결과에서 계산됩니다. 병합 전에 결과를 확인하는 것은 해당 점수가 표류하지 않도록 하는 방법입니다. 메트릭 및 점수 참조을(를) 참조하세요.
백로그. 끌어오기 요청에서 수정하지 않는 모든 항목은 기본 분기에 있는 결과의 백로그에 조인됩니다. 그 백로그를 줄여 나가는 것 자체가 하나의 기술입니다. 리포지토리의 코드 품질 점수 올리기을(를) 참조하세요.
준수. 특정 유형의 발견 사항이 정말로 기본 브랜치에 병합되지 않도록 해야 하는 경우, "코드 품질 결과 필요" 규칙 세트를 사용하면 리포지토리 관리자와 조직 소유자가 그 결정을 병합 조건으로 반영할 수 있습니다. 끌어오기 요청에서 블록 해결을(를) 참조하세요.

가장 건강한 팀은 끌어오기 요청 단계에서 의도적인 심사 및 수정, 주기적인 백로그 작업, 병합 경계에 적용된 임계값의 세 가지를 모두 결합합니다.

Troubleshooting

나는 어떤 Code Quality 의견을 볼 수 없습니다. 검색이 계속 실행 중이거나, 변경 내용이 지원되는 언어에 영향을 주지 않거나, 검색 결과가 없을 수 있습니다. 확인 Code Quality 이 활성화되어 있는지 확인하고 확인을 완료할 시간을 줍니다("CodeQL - 코드 품질"라고 함). GitHub Code Quality 사용을(를) 참조하세요.
저는 github-code-quality[bot]의 댓글만 보고, Copilot의 댓글은 전혀 보지 못합니다. AI 기반 결과에는 엔터프라이즈에 대해 사용하도록 설정된 라이선스 및 AI 기능이 필요합니다 Copilot . 이러한 항목이 없으면 규칙 기반 결과만 표시됩니다.
내 코드 품질 문제에 대한 자동 수정이 표시되지 않습니다. Autofix 생성은 GitHub AI Credits를 소모합니다. 조직의 AI credits 월별 예산이 소진되었을 수 있습니다.
병합 블록 배너가 지워지지 않습니다. 차단 심각도 이상의 항목이 하나 이상 아직 미해결 상태입니다. 병합 블록 배너에 정의된 심각도 수준이 표시되지 않으면 리포지토리가 가장 엄격한 코드 품질 임계값을 사용하고 있음을 의미하며, 병합하기 전에 모든 결과를 해결해야 합니다. 끌어오기 요청에서 블록 해결을(를) 참조하세요.

결론

이 자습서에서는 Code Quality끌어오기 요청의 댓글을 하나씩 검토하고 처리했으며, 심각도를 기준으로 수정 우선순위를 정하고, 끌어오기 요청을 병합하기 전에 각 발견 사항을 신중하게 해결했습니다. 각 발견 사항과 해당 자동 수정을 문맥에 맞는 작은 결정으로 처리함으로써 코드 품질 부채가 기본 브랜치에까지 쌓이지 않도록 했습니다.

다음 단계

기존 백로그인 리포지토리의 코드 품질 점수 올리기에 동일한 생각을 적용합니다.
작업의 영향을 측정할 수 있도록 결과를 점수로 변환하는 방법을 알아봅니다. 메트릭 및 점수 참조.