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

심각도 레이블의 의미, 각 지적 사항을 언제 수정하고, 위임하거나, 무시하는 것이 가장 적절한지, 그리고 이러한 선택이 리포지토리의 코드 건전성에 어떤 영향을 미치는지를 포함해 풀 리퀘스트의 Code Quality 지적 사항을 살펴보세요.

## Introduction

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

* 끌어오기 요청에 대한 주석을 읽 Code Quality 는 방법입니다.
* 찾기의 심각도 레이블을 사용하여 수정할 항목, 해제할 항목 및 순서를 결정하는 방법입니다.
* 끌어오기 요청에서 선택한 항목이 리포지토리의 점수, 백로그 및 병합 게이트를 구성하는 방식입니다.

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

이것은 단계별 안내이므로 속도보다 이해를 우선합니다. 자동 수정을 커밋하거나 탐지 결과를 무시하는 방법에 대한 기본 단계는 관련 방법 문서 [끌어오기 요청에서 코드 품질 결과 수정](/ko/code-security/how-tos/maintain-quality-code/fix-findings-on-a-pr)를 참조하세요.

### 시작하기 전에

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

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

## 끌어오기 요청이 찾기를 해결하기에 가장 적합한 이유

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

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

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

끌어오기 요청을 Code QualityCodeQL 열 때 규칙 집합에 대한 변경 내용을 검색하고 결과를 메모로 게시합니다 `github-code-quality[bot]`. 각 주석에는 제안된 자동 접두사를 포함합니다. 끌어오기 요청의 **변경된 파일** 탭을 열어 결과를 검토합니다.

이 예제에서는 3개의 주석을 `github-code-quality[bot]`살펴보겠습니다. 각각에 대한 심각도 레이블을 적어 둡니다. 2단계에서는 그 의미를 설명합니다.

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

모든 검색 결과에 `github-code-quality[bot]` 는 심각도 레이블(**오류**, **경고** 또는 **참고**)이 있습니다. 댓글 중 하나에서 레이블을 찾아 이 표와 대조해 확인하세요.

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

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

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

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

![끌어오기 요청의 체크 섹션에 있는 병합 블록 배너의 스크린샷](/assets/images/help/code-quality/code-quality-merge-block.png)

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

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

## 3단계: 각 발견 사항 해결

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

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

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

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

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

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

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

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

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

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

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

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

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

## Troubleshooting

* **나는 어떤 Code Quality 의견을 볼 수 없습니다.** 검색이 계속 실행 중이거나, 변경 내용이 지원되는 언어에 영향을 주지 않거나, 검색 결과가 없을 수 있습니다. 확인 Code Quality 이 활성화되어 있는지 확인하고 확인을 완료할 시간을 줍니다("CodeQL - 코드 품질"라고 함).
  [GitHub Code Quality 사용](/ko/code-security/how-tos/maintain-quality-code/enable-code-quality)을(를) 참조하세요.
* **내 코드 품질 문제에 대한 자동 수정이 표시되지 않습니다.** Autofix 생성은 GitHub AI Credits를 소모합니다. 조직의 AI credits 월별 예산이 소진되었을 수 있습니다.
* **병합 블록 배너가 지워지지 않습니다.** 차단 심각도 이상의 항목이 하나 이상 아직 미해결 상태입니다. 병합 블록 배너에 정의된 심각도 수준이 표시되지 않으면 리포지토리가 가장 엄격한 코드 품질 임계값을 사용하고 있음을 의미하며, 병합하기 전에 *모든* 결과를 해결해야 합니다.
  [끌어오기 요청에서 블록 해결](/ko/code-security/how-tos/maintain-quality-code/unblock-your-pr)을(를) 참조하세요.

## 결론

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

## 다음 단계

* 기존 백로그인 [리포지토리의 코드 품질 점수 올리기](/ko/code-security/tutorials/improve-code-quality/raise-your-quality-rating)에 동일한 생각을 적용합니다.
* 작업의 영향을 측정할 수 있도록 결과를 점수로 변환하는 방법을 알아봅니다. [메트릭 및 점수 참조](/ko/code-security/reference/code-quality/metrics-and-ratings).