# 필수 상태 검사 문제 해결

일반적인 오류를 해결하고 필수 상태 검사를 점검하여 보호된 분기에 병합하거나 푸시할 때 발생하는 차단 문제를 해결합니다.

필수 상태 검사로 인해 병합이나 보호된 브랜치로의 푸시가 차단될 때 다음 검사를 사용하세요.
[Status checks](/ko/pull-requests/reference/status-checks)을(를) 참조하세요.

* 지난 7일 동안 선택한 리포지토리에서 필수 상태 검사가 성공적으로 완료되어야 합니다.
* 검사와 커밋 상태의 이름이 같은 경우, 해당 이름이 필수인 경우 둘 다 통과해야 합니다.
  [검사에 대한 REST API 엔드포인트](/ko/rest/checks)을(를) 참조하세요.
* 브랜치 보호 규칙에 따라 브랜치가 최신 상태여야 하는 경우, 기준 브랜치를 현재 브랜치에 병합하거나 현재 브랜치를 기준 브랜치로 리베이스하세요.
  [보호된 분기 정보](/ko/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) 및 [Git 리베이스에 대하여](/ko/get-started/using-git/about-git-rebase)을(를) 참조하세요.

필요한 상태 검사가 통과되지 않은 경우 보호된 분기로 푸시하면 이와 유사한 오류가 반환됩니다.

```shell
remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Required status check "ci-build" is failing
```

> \[!NOTE]
> 최신 상태이고 필수적인 상태 확인을 통과한 풀 리퀘스트는 로컬에서 병합한 후 보호된 브랜치로 푸시할 수 있습니다. 병합 커밋 자체에 대한 상태 검사를 실행하지 않고도 이 작업을 수행할 수 있습니다.

## 최신 커밋의 SHA 값에 대해 필수 검사를 통과해야 합니다.

필요한 검사가 여전히 끌어오기 요청을 차단하고 있는지 다음을 확인합니다.

* 필수 검사는 최신 커밋 SHA에서 통과해야 합니다. 이전 커밋의 검사는 요구 사항을 충족하지 않습니다.
* 성공적인 확인 상태는 `success`, `skipped`및 `neutral`.
  [Status checks](/ko/pull-requests/reference/status-checks)을(를) 참조하세요.

## 헤드 커밋과 테스트 병합 커밋 간의 충돌

끌어오기 요청 상태 확인란을 사용하여 전달해야 하는 커밋을 식별합니다.

| 상태 검사 원본             | 통과해야 하는 사항 | 볼 수 있는 내용                             |
| -------------------- | ---------- | ------------------------------------- |
| 테스트 병합 커밋에 상태가 있습니다. | 테스트 병합 커밋  | `Showing checks for the merge commit` |
| 테스트 병합 커밋에 상태가 없습니다  | 헤드 커밋      | 최신 HEAD 커밋을 확인합니다                     |

[끌어오기 요청에 대한 REST API 엔드포인트](/ko/rest/pulls/pulls#get-a-pull-request)을(를) 참조하세요.

## 건너뛰었으나 필요한 검사 처리

| 원인                                                                                                                                                                                                                                                                                                                                               | Result                             | 수정하거나 확인하는 방법                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | --------------------------------------------------- |
| [경로 필터링](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore), [분기 필터링](/ko/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore) 또는 [커밋 메시지](/ko/actions/how-tos/manage-workflow-runs/skip-workflow-runs)로 워크플로 건너뛰기 | 연결된 검사는 "보류 중" 상태로 유지되고 병합을 차단합니다. | 건너뛸 수 있는 워크플로가 필요하지 않습니다.                           |
| 조건에 따라 작업이 건너뛰어집니다                                                                                                                                                                                                                                                                                                                               | 작업 상태가 "Success"로 표시됩니다.           |                                                     |
| [조건을 사용하여 작업 실행 제어](/ko/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions)을(를) 참조하세요.                                                                                                                                                                                                                       |                                    |                                                     |
| 작업은 실패한 작업에 따라 달라집니다.                                                                                                                                                                                                                                                                                                                            | 종속 작업은 건너뛰어지며 병합이 차단되지 않을 수 있습니다.  | 다른 작업에 종속된 필수 검사를 위해 `always()`를 `needs`와 함께 사용하세요. |
| [워크플로의 작업 사용](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs)을(를) 참조하세요.                                                                                                                                                                                                                       |                                    |                                                     |

### 예시

이 워크플로에는 성공적인 `build` 작업이 필요하지만 끌어오기 요청이 파일을 `scripts`변경하는 경우에만 실행됩니다.

```yaml
name: ci
on:
  pull_request:
    paths:
      - 'scripts/**'
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [12.x, 14.x, 16.x]
    steps:
    - uses: actions/checkout@v6
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test
```

리포지토리 루트의 파일만 변경하는 끌어오기 요청은 이 워크플로를 트리거하지 않습니다. 필요한 경우 `build` 끌어오기 요청은 "상태가 보고될 때까지 대기 중"으로 차단됩니다.

### GitHub Actions 및 병합 큐를 사용한 상태 검사

병합 큐에 GitHub Actions 검사가 필요한 경우, `merge_group` 이벤트로 워크플로를 트리거하세요.

> \[!NOTE]
> 리포지토리에서 GitHub Actions을(를) 사용하여 필요한 검사 을(를) 통해 워크플로가 필요한 경우 `merge_group` 이벤트를 추가 트리거로 포함하도록 워크플로를 업데이트해야 합니다. 그렇지 않으면 병합 큐에 끌어오기 요청을 추가할 때 상태 검사가 트리거되지 않습니다. 상태 확인 필요가 보고되지 않으므로 병합이 실패합니다. `merge_group` 이벤트는 `pull_request` 및 `push` 이벤트트와 별개입니다.

트리거 구성 예제:

```yaml
on:
  pull_request:
  merge_group:
```

[워크플로를 트리거하는 이벤트](/ko/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group)을(를) 참조하세요.

## 예기치 않은 출처의 필수 상태 검사

보호된 브랜치는 특정 GitHub App의 상태 확인을 요구할 수도 있습니다. 다음과 유사한 메시지가 표시되면 병합 상자에 나열된 확인란이 예상된 앱에 의해 설정되었는지 확인합니다.

```text
Required status check "build" was not set by the expected GitHub App.
```