워크플로우 문제 해결하기

워크플로우 문제 해결하기

GitHub Actions의 도구를 사용해 워크플로우를 디버그할 수 있어요.

출처: 문서

본문

GitHub Actions의 도구를 사용해 워크플로우를 디버그할 수 있어요.

초기 문제 해결 제안

실패한 워크플로우 실행을 문제 해결하는 방법은 여러 가지가 있어요.

[!NOTE] GitHub Copilot Free 구독 중이라면 이 내용은 월간 채팅 메시지 한도에 포함됩니다.

GitHub Copilot 사용하기

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

  • 병합 상자의 실패한 체크 옆에서 ****을 클릭한 다음 Explain error을 클릭하세요.
  • 병합 상자에서 실패한 체크를 클릭하세요. 워크플로우 실행 요약 페이지 맨 위에서 Explain error을 클릭하세요.

이렇게 하면 GitHub Copilot과 채팅 창이 열리고, 문제 해결 지침을 제공합니다.

워크플로우 실행 로그 사용하기

각 워크플로우 실행은 보고, 검색하고, 다운로드할 수 있는 활동 로그를 생성해요. 자세한 내용은 Using workflow run logs를 참고하세요.

디버그 로깅 활성화하기

워크플로우 로그로 워크플로우, 작업, 단계가 예상대로 작동하지 않는 이유를 진단하기에 충분하지 않다면 추가 디버그 로깅을 활성화할 수 있어요. 자세한 내용은 Enabling debug logging을 참고하세요.

워크플로우가 특정 도구나 액션을 사용한다면, 디버그 또는 verbose 로깅 옵션을 활성화하면 문제 해결에 더 상세한 출력을 생성하는 데 도움이 될 수 있어요. 예를 들어 npm에는 npm install --verbose를, git에는 GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ...을 사용할 수 있어요.

청구 오류 검토하기

Actions 사용량에는 워크플로우 아티팩트에 대한 러너 분(runner minutes)과 저장 공간이 포함됩니다. 자세한 내용은 GitHub Actions billing을 참고하세요.

예산 설정하기

Actions 예산을 설정하면 청구 또는 저장 오류로 실패하는 워크플로우를 즉시 차단 해제하는 데 도움이 될 수 있어요. 설정한 예산 금액까지 추가 분 및 저장 공간 사용량이 청구되도록 허용됩니다. 자세한 내용은 Setting up budgets to control spending on metered products을 참고하세요.

지표로 GitHub Actions 활동 검토하기

지표를 사용해 워크플로우의 효율성과 안정성을 분석하려면 Viewing GitHub Actions metrics를 참고하세요.

워크플로우 트리거 문제 해결하기

먼저 워크플로우가 수동으로 비활성화되지 않았는지 확인하세요. Disabling and enabling a workflow 참고. 비활성화된 워크플로우는 트리거에 응답하지 않습니다.

워크플로우의 on: 필드를 검토해 무엇이 워크플로우를 트리거할 것으로 예상되는지 이해할 수 있어요. 자세한 내용은 Triggering a workflow를 참고하세요.

사용 가능한 전체 이벤트 목록은 Events that trigger workflows를 참고하세요.

트리거 이벤트 조건

일부 트리거 이벤트는 기본 브랜치에서만 실행됩니다(예: issues, schedule). 기본 브랜치 밖에 존재하는 워크플로우 파일 버전은 이러한 이벤트에서 트리거되지 않아요.

풀 리퀘스트에 병합 충돌이 있으면 pull_request 활동에서 워크플로우가 실행되지 않습니다.

커밋 메시지에 건너뛰기 주석(skip annotation)이 포함되어 있으면, 그렇지 않으면 push 또는 pull_request 활동에서 트리거될 워크플로우가 건너뛰어집니다. 자세한 내용은 Skipping workflow runs을 참고하세요.

예상치 못한 시간에 실행되는 예약 워크플로우

예약 이벤트는 GitHub Actions 워크플로우 실행 부하가 높은 기간 동안 지연될 수 있어요.

높은 부하 시간에는 매 시간의 시작이 포함됩니다. 부하가 충분히 높으면 일부 대기 중인 작업이 삭제될 수 있어요. 지연 가능성을 줄이려면 워크플로우를 시간의 다른 시점에 실행되도록 예약하세요. 자세한 내용은 Events that trigger workflows를 참고하세요.

필터링 및 diff 제한

특정 이벤트는 커스터마이즈할 수 있는 브랜치, 태그 및/또는 경로로 필터링할 수 있어요. 필터 조건이 워크플로우를 걸러내는 경우 워크플로우 실행 생성은 건너뛰어집니다.

필터와 함께 특수 문자를 사용할 수 있어요. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

경로 필터링의 경우 diff 평가는 처음 3,000개 파일로 제한됩니다. 필터가 반환한 처음 3,000개 파일에 일치하지 않는 변경된 파일이 있으면 워크플로우가 실행되지 않습니다. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

워크플로우 실행 문제 해결

워크플로우 실행은 워크플로우가 트리거되고 워크플로우 실행이 생성된 후에 발생하는 모든 문제를 포함합니다.

작업 조건 디버깅하기

작업이 예상치 못하게 건너뛰어졌거나, 건너뛸 것으로 예상했는데 실행되었다면 표현식 평가를 보면 이유를 이해할 수 있어요:

  1. 워크플로우 실행에서 작업을 클릭하세요.
  2. 작업의 메뉴에서 로그 아카이브를 다운로드하세요.
  3. JOB-NAME/system.txt 파일을 여세요.
  4. Evaluating, Expanded, Result 줄을 찾으세요.

Expanded 줄은 if 조건에 치환된 실제 런타임 값을 보여주며, 표현식이 true 또는 false로 평가된 이유를 명확히 합니다.

자세한 내용은 Viewing job condition expression logs을 참고하세요.

워크플로우 취소하기

UI 또는 API를 통한 표준 취소가 예상대로 처리되지 않으면, 실행 중인 워크플로우 작업에 취소되지 않게 하는 조건문이 구성되어 있을 수 있어요.

이런 경우 API를 활용해 실행을 강제 취소할 수 있어요. 자세한 내용은 REST API endpoints for workflow runs을 참고하세요.

흔한 원인은 취소 시에도 true를 반환하는 always() 상태 확인 함수를 사용하는 것입니다. 대안으로 cancelled() 함수의 역인 ${{ !cancelled() }}을 사용할 수 있어요.

자세한 내용은 Using conditions to control job execution과 Canceling a workflow run을 참고하세요.

러너 문제 해결

러너 라벨 정의하기

GitHub 호스팅 러너는 actions/runner-images 저장소를 통해 유지 관리되는 사전 설정 라벨을 활용합니다.

대형 러너와 셀프 호스팅 러너에는 고유한 라벨 이름을 사용할 것을 권장합니다. 라벨이 기존 사전 설정 라벨 중 하나와 일치하면, 작업이 어떤 일치 러너 옵션에서 실행될지 보장할 수 없는 러너 할당 문제가 발생할 수 있어요.

셀프 호스팅 러너

셀프 호스팅 러너를 사용한다면 그 활동을 보고 일반적인 문제를 진단할 수 있어요.

자세한 내용은 Monitoring and troubleshooting self-hosted runners를 참고하세요.

보안 스캐너가 플래그한 러너 IP 주소

GitHub 호스팅 러너는 공유 인프라에서 동적으로 할당된 IP 주소를 사용합니다. 이 IP 주소들은 Meta API를 통해 게시됩니다(예: actions 및 actions_macos 키). 자세한 내용은 REST API endpoints for meta data를 참고하세요.

타사 위협 인텔리전스 서비스, IP 평판 스캐너 또는 방화벽 벤더가 이러한 IP 주소를 "악성" 또는 "의심스러운" 것으로 플래그할 수 있어요. 기반 인프라가 공유되므로 같은 인프라의 다른 사용자 활동이 이 주소에 할당된 평판 점수에 영향을 줄 수 있습니다.

GitHub는 타사 IP 평판 목록을 제어하지 않으며 그 정확성이나 업데이트 빈도에 대해 언급할 수 없어요. IP 주소가 GitHub 호스팅 러너에 속하는지 확인하려면 Meta API가 반환하는 IP 범위를 확인하세요.

Microsoft 소유 IP 주소에 대한 보안 우려가 있다면 Microsoft Security Response Center (MSRC)에 신고하세요.

네트워킹 문제 해결 제안

다음을 포함하는 네트워크 문제에 대한 지원은 제한적입니다:

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

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

다른 네트워크 관련 문제에 대해서는 조직의 네트워크 설정을 검토하고 접근 중인 타사 서비스의 상태를 확인하세요. 문제가 지속되면 네트워크 관리자에게 문의해 추가 지원을 받는 것을 고려하세요.

문제가 확실하지 않다면 GitHub Support에 문의하세요. 지원 문의 방법에 대한 자세한 내용은 Contacting GitHub Support를 참고하세요.

DNS

도메인 이름 시스템(DNS) 구성, 해석 또는 리졸버(resolver) 문제로 인해 문제가 발생할 수 있어요. 사용 가능한 로그, 벤더 문서를 검토하거나 관리자에게 문의해 추가 지원을 받는 것을 권장합니다.

방화벽

활동이 방화벽에 의해 차단될 수 있어요. 이런 경우 사용 가능한 로그, 벤더 문서를 검토하거나 관리자에게 문의해 추가 지원을 받는 것을 고려하세요.

프록시

통신에 프록시를 사용할 때 활동이 실패할 수 있어요. 사용 가능한 로그, 벤더 문서를 검토하거나 관리자에게 문의해 추가 지원을 받는 것이 좋습니다.

프록시를 활용하도록 러너 애플리케이션 구성에 대한 정보는 Using proxy servers with a runner를 참고하세요.

서브넷

사용 중인 서브넷이나 기존 네트워크(예: 가상 클라우드 공급자 또는 Docker 네트워크 내)와의 겹침 문제가 발생할 수 있어요. 이런 경우 네트워크 토폴로지와 사용 중인 서브넷을 검토할 것을 권장합니다.

인증서

자가 서명 또는 커스텀 인증서 체인과 인증서 저장소로 인해 문제가 발생할 수 있어요. 사용 중인 인증서가 만료되지 않았고 현재 신뢰되는지 확인할 수 있어요. 인증서는 curl 또는 유사한 도구로 검사할 수 있습니다. 또한 사용 가능한 로그, 벤더 문서를 검토하거나 관리자에게 문의해 추가 지원을 받을 수 있어요.

IP 목록

IP 허용 또는 거부 목록이 예상 통신을 방해할 수 있어요. 문제가 있다면 사용 가능한 로그, 벤더 문서를 검토하거나 관리자에게 문의해 추가 지원을 받아야 합니다.

GitHub 호스팅 러너가 사용하는 주소와 같은 GitHub IP 주소에 대한 정보는 About GitHub's IP addresses를 참고하세요.

GitHub 호스팅 대형 러너와 함께 사용할 수 있는 고정 IP 주소가 있습니다. 자세한 내용은 Managing larger runners를 참고하세요.

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

방화벽이나 프록시 외에도 GitHub 호스팅 러너에 수행된 커스터마이제이션(예: 추가 소프트웨어 패키지 설치)으로 인해 통신 중단이 발생할 수 있어요. 사용 가능한 커스터마이제이션 옵션에 대한 정보는 Customizing GitHub-hosted runners를 참고하세요.

GitHub 호스팅 러너용 Azure 비공개 네트워킹

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

문제 해결 조언은 GitHub Enterprise Cloud 문서의 Troubleshooting Azure private network configurations for GitHub-hosted runners in your organization 또는 Troubleshooting Azure private network configurations for GitHub-hosted runners in your enterprise를 참고하세요.

더 알아보기 (Learn more)