문제 해결 워크플로

GitHub Actions의 도구를 사용하여 워크플로를 디버그할 수 있습니다.

이 문서의 내용

초기 문제 해결 제안

실패한 워크플로 실행 문제를 해결할 수 있는 몇 가지 방법이 있습니다.

참고 항목

GitHub Copilot Free 구독을 사용하는 경우, 이 채팅은 월별 채팅 메시지 제한에 포함됩니다.

GitHub Copilot 사용

실패한 워크플로 실행에 대해 GitHub Copilot과 채팅을 열려면 다음 중 하나를 수행할 수 있습니다.

  • 병합 상자에서 실패한 확인 상자 옆에 있는 을 클릭한 다음, Explain error를 클릭합니다.
  • 병합 상자에서 실패한 확인 상자를 클릭합니다. 워크플로 실행 요약 페이지의 맨 위에서 Explain error를 클릭합니다.

이렇게 하면 GitHub Copilot과의 채팅 창이 열리고, 여기서 문제를 해결하기 위한 지침을 제공합니다.

워크플로 실행 로그 사용

각 워크플로 실행은 보고, 검색하고, 다운로드할 수 있는 활동 로그를 생성합니다. 자세한 내용은 워크플로 실행 로그 사용을(를) 참조하세요.

디버그 로깅 사용

워크플로 로그가 워크플로, 작업 또는 단계가 예상대로 작동하지 않는 이유를 진단하기에 충분한 세부 정보를 제공하지 않는 경우 추가 디버그 로깅을 사용하도록 설정할 수 있습니다. 자세한 내용은 디버그 로깅 사용을(를) 참조하세요.

워크플로에서 특정 도구 또는 작업을 사용하는 경우 디버그 또는 자세한 로깅 옵션을 사용하도록 설정하면 문제 해결을 위한 자세한 출력을 생성하는 데 도움이 될 수 있습니다. 예를 들어 npm에 대해 npm install --verbose, git에 대해 GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ...을 사용할 수 있습니다.

청구 오류 검토

작업 사용량에는 워크플로 아티팩트용 실행기 시간(분) 및 스토리지가 포함됩니다. 자세한 내용은 GitHub Actions 청구을(를) 참조하세요.

예산 설정

작업 예산을 설정하면 청구 또는 스토리지 오류로 인해 실패한 워크플로의 차단을 즉시 해제하는 데 도움이 될 수 있습니다. 추가 시간(분)과 스토리지 사용량에 대한 비용은 설정된 예산 금액까지 청구될 수 있습니다. 자세한 내용은 예산을 설정하여 요금제 제품에 대한 지출 제어을(를) 참조하세요.

메트릭을 사용하여 GitHub Actions 활동 검토

메트릭을 사용하여 워크플로의 효율성과 안정성을 분석하려면 GitHub Actions 메트릭 보기을(를) 참조하세요.

워크플로 트리거 문제 해결

워크플로의 on: 필드를 검토하여 워크플로의 예상 트리거 조건을 이해할 수 있습니다. 자세한 내용은 워크플로 트리거을(를) 참조하세요.

사용 가능한 이벤트의 전체 목록은 워크플로를 트리거하는 이벤트을(를) 참조하세요.

트리거 이벤트 조건

일부 트리거 이벤트는 기본 분기(즉, issues, schedule)에서만 실행됩니다. 기본 분기 외부에 있는 워크플로 파일 버전은 이러한 이벤트에서 트리거되지 않습니다.

끌어오기 요청에 병합 충돌이 있는 경우 워크플로는 pull_request 작업에서 실행되지 않습니다.

push 또는 pull_request 활동에 대해 트리거될 워크플로의 경우라도 커밋 메시지에 주석 건너뛰기가 포함되어 있으면 건너뜁니다. 자세한 내용은 워크플로 실행 건너뛰기을(를) 참조하세요.

예약된 워크플로가 예기치 않은 시간에 실행

GitHub Actions 워크플로가 실행되는 로드가 많은 기간 동안 예약된 이벤트가 지연될 수 있습니다.

높은 로드 시간에는 매 시간의 시작이 포함됩니다. 부하가 높으면 대기 중인 작업 일부가 삭제될 수 있습니다. 지연 가능성을 줄이려면 워크플로가 다른 시간에 실행되도록 예약합니다. 자세한 내용은 워크플로를 트리거하는 이벤트을(를) 참조하세요.

필터링 및 차이 제한

특정 이벤트를 사용하면 사용자 지정할 수 있는 분기, 태그 및/또는 경로별로 필터링할 수 있습니다. 워크플로를 필터링하기 위해 필터 조건이 적용되는 경우 워크플로 실행 만들기를 건너뜁니다.

필터와 함께 특수 문자를 사용할 수 있습니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

경로 필터링의 경우 차이점 평가는 처음 300개 파일로 제한됩니다. 필터에서 반환된 처음 300개 파일에서 일치하지 않는 파일이 변경된 경우 워크플로가 실행되지 않습니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

워크플로 실행 문제 해결

워크플로 실행에는 워크플로가 트리거되고 워크플로 실행이 생성된 후에 확인된 모든 문제가 포함됩니다.

워크플로 취소

UI 또는 API를 통한 표준 취소가 예상대로 진행되지 않는 경우 실행 중인 워크플로 작업에 대해 취소되지 않도록 하는 조건문이 구성되어 있을 수 있습니다.

이러한 경우 API를 활용하여 실행을 강제로 취소할 수 있습니다. 자세한 내용은 워크플로 실행에 대한 REST API 엔드포인트을(를) 참조하세요.

일반적인 원인은 취소 시에도 true를 반환하는 always() 상태 검사 함수를 사용하는 경우일 수 있습니다. 대안은 cancelled() 함수, ${{ !cancelled() }}를 역으로 사용하는 것입니다.

자세한 내용은 조건을 사용하여 작업 실행 제어 및 워크플로 실행 취소을(를) 참조하세요.

실행기 문제 해결

실행기 레이블 정의

GitHub 호스팅 실행기는 actions/runner-images 리포지토리를 통해 유지 관리되는 미리 설정된 레이블을 활용합니다.

더 큰 자체 호스팅 실행기의 경우 고유한 레이블 이름을 사용하는 것이 좋습니다. 레이블이 미리 설정된 기존의 레이블과 일치하는 경우 작업이 실행될 일치하는 실행기 옵션이 보장되지 않는 실행기 할당 문제가 있는 것일 수 있습니다.

자체 호스팅 실행기

자체 호스팅 실행기를 사용하는 경우 해당 활동을 보고 일반적인 문제를 진단할 수 있습니다.

자세한 내용은 자체 호스트형 실행기 모니터링 및 문제 해결을(를) 참조하세요.

네트워킹 문제 해결 제안

다음과 같은 네트워크 문제를 위한 지원이 제한됩니다.

  • 네트워크
  • 외부 네트워크
  • 타사 시스템
  • 일반적인 인터넷 연결

GitHub의 실시간 플랫폼 상태를 보려면 GitHub 상태를 확인하세요.

다른 네트워크 관련 이슈의 경우, 조직의 네트워크 설정을 검토하고 액세스 중인 타사 서비스의 상태를 확인하세요. 문제가 지속되면 네트워크 관리자에게 연락하여 추가 지원을 요청하세요.

해당 문제에 대해 확신이 없다면 GitHub 지원에 문의하세요. 지원팀에 문의하는 방법에 대한 자세한 내용은 GitHub 지원에 문의을(를) 참조하세요.

DNS

이슈는 DNS(Domain Name System) 구성, 해석, 또는 확인자 문제로 인해 발생할 수 있습니다. 이 경우 사용 가능한 로그, 공급업체 문서 검토, 또는 관리자에게 문의하여 추가 지원을 받는 것을 권장합니다.

방화벽

방화벽에 의해 활동이 차단될 수 있습니다. 이 경우 사용 가능한 로그, 공급업체 문서 검토, 또는 관리자에게 문의하여 추가 지원을 받는 것을 권장합니다.

프록시

통신에 프록시를 사용하면, 활동이 실패할 수 있습니다. 사용 가능한 로그, 공급업체 문서를 검토하거나 관리자에게 문의하여 추가 지원을 받는 것이 좋습니다.

프록시를 활용하기 위해 러너 애플리케이션을 구성하는 방법에 대한 자세한 내용은 자체 호스트형 실행기를 사용하는 프록시 서버 사용을(를) 참조하세요.

서브넷

사용 중인 서브넷에 문제가 발생하거나 또는 기존 네트워크(가상 클라우드 공급자 또는 Docker 네트워크)와의 중복으로 인해 문제가 발생할 수 있습니다. 이 경우 네트워크 토폴로지와 사용 중인 서브넷을 검토할 것을 권장합니다.

인증서

자체 서명 또는 사용자 지정 인증서 체인 및 인증서 저장소에서 문제가 발생할 수 있습니다. 사용 중인 인증서가 만료되지 않았으며 현재 신뢰할 수 있는 상태인지 확인할 수 있습니다. 인증서는 curl 또는 이와 유사한 도구를 통해 검사할 수 있습니다. 또한, 사용 가능한 로그, 공급업체 문서 검토, 또는 관리자에게 문의하여 추가 지원을 받을 수 있습니다.

IP 목록

IP 허용 또는 거부 목록은 예상된 통신을 방해할 수 있습니다. 문제가 발생하면 사용 가능한 로그, 공급업체 문서 검토, 또는 관리자에게 문의하여 추가 지원을 받는 것을 권장합니다.

GitHub 호스팅 러너에서 사용되는 주소와 같은 GitHub의 IP 주소에 대한 정보는 GitHub IP 주소 정보을(를) 참조하세요.

고정 IP 주소는 GitHub 호스팅 러너에서 사용할 수 있습니다. 자세한 내용은 대형 실행기 관리하기을(를) 참조하세요.

운영 체제 및 소프트웨어 애플리케이션

방화벽 또는 프록시 외에도, 추가 소프트웨어 패키지 설치 등 GitHub 호스팅 러너에서 수행되는 사용자 지정 작업으로 인해 통신이 중단될 수 있습니다. 사용 가능한 사용자 지정 옵션에 대한 자세한 내용은 GitHub 호스팅 실행기 사용자 지정을(를) 참조하세요.

GitHub 호스팅 러너의 Azure 개인 네트워킹

구성된 Azure VNET(Virtual Networks) 설정 내에서 GitHub 호스팅 러너를 사용하면 문제가 발생할 수 있습니다.

문제 해결을 위한 조언은 조직에서 GitHub 호스트형 실행기를 위한 Azure 개인 네트워크 구성 문제 해결 또는 GitHub Enterprise Cloud 문서의 엔터프라이즈의 GitHub 호스트형 실행기에 대한 Azure 개인 네트워크 구성 문제 해결을(를) 참조하세요.