{"meta":{"title":"워크플로 문제 해결","intro":"도구를 GitHub Actions 사용하여 워크플로를 디버그할 수 있습니다.","product":"GitHub Actions","breadcrumbs":[{"href":"/ko/enterprise-cloud@latest/actions","title":"GitHub Actions"},{"href":"/ko/enterprise-cloud@latest/actions/how-tos","title":"사용법"},{"href":"/ko/enterprise-cloud@latest/actions/how-tos/troubleshoot-workflows","title":"워크플로 문제 해결"}],"documentType":"article"},"body":"# 워크플로 문제 해결\n\n도구를 GitHub Actions 사용하여 워크플로를 디버그할 수 있습니다.\n\n## 초기 문제 해결 제안\n\n실패한 워크플로 실행을 문제 해결하는 방법은 여러 가지가 있습니다.\n\n> \\[!NOTE]\n> GitHub Copilot Free 구독을 이용 중인 경우, 이 메시지는 월별 채팅 메시지 한도에 포함됩니다.\n\n### GitHub Copilot 사용하기\n\n실패한 워크플로 실행에 대한 채팅 GitHub Copilot 을 열려면 다음 중 하나를 수행할 수 있습니다.\n\n* 병합 상자에서 실패한 검사 옆에 있는 **** 를 클릭한 다음, **오류 설명**을 클릭합니다.\n* 병합 상자에서 실패한 체크를 클릭합니다. 워크플로 실행 요약 페이지의 맨 위에서 **설명 오류를 클릭합니다**.\n\n그러면 문제를 해결하기 위한 지침이 제공되는 채팅 창 GitHub Copilot이 열립니다.\n\n### 워크플로 실행 로그 사용\n\n각 워크플로 실행은 보고, 검색하고, 다운로드할 수 있는 활동 로그를 생성합니다. 자세한 내용은 [워크플로 실행 로그 사용](/ko/enterprise-cloud@latest/actions/how-tos/monitor-workflows/use-workflow-run-logs)을(를) 참조하세요.\n\n### 디버그 로깅 사용\n\n워크플로 로그가 워크플로, 작업 또는 단계가 예상대로 작동하지 않는 이유를 진단하기에 충분한 세부 정보를 제공하지 않는 경우 추가 디버그 로깅을 사용하도록 설정할 수 있습니다. 자세한 내용은 [디버그 로깅 활성화](/ko/enterprise-cloud@latest/actions/how-tos/monitor-workflows/enable-debug-logging)을(를) 참조하세요.\n\n워크플로에서 특정 도구 또는 작업을 사용하는 경우, 해당 도구의 디버그 또는 자세한 로깅 옵션을 활성화하면 문제 해결을 위한 더 자세한 출력을 생성하는 데 도움이 될 수 있습니다.\n예를 들어 npm에는 `npm install --verbose`을(를) 사용하고 git에는 `GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ...`을(를) 사용할 수 있습니다.\n\n## 청구 오류 검토\n\n작업 사용량에는 [워크플로 아티팩트](/ko/enterprise-cloud@latest/actions/tutorials/store-and-share-data)에 대한 실행기 시간(분)과 스토리지가 포함됩니다. 자세한 내용은 [GitHub Actions 비용 청구](/ko/enterprise-cloud@latest/billing/concepts/product-billing/github-actions)을(를) 참조하세요.\n\n### 예산 설정\n\n작업 예산을 설정하면 청구 또는 스토리지 오류로 인해 실패하는 워크플로를 즉시 차단 해제하는 데 도움이 될 수 있습니다. 설정된 예산 금액까지 추가 시간(분)과 스토리지 사용량이 청구되도록 허용합니다. 자세한 내용은 [예산을 설정하여 요금제 제품에 대한 지출을 제어합니다.](/ko/enterprise-cloud@latest/billing/how-tos/set-up-budgets)를 참조하세요.\n\n## 메트릭을 사용하여 작업 검토 GitHub Actions\n\n메트릭을 사용하여 워크플로의 효율성과 안정성을 분석하는 방법은 [GitHub Actions 메트릭 보기](/ko/enterprise-cloud@latest/actions/how-tos/administer/view-metrics)을(를) 참조하세요.\n\n## 워크플로 트리거 문제 해결\n\n먼저 워크플로를 수동으로 사용하지 않도록 설정하지 않았는지 확인합니다. [워크플로를 사용/사용하지 않도록 설정](/ko/enterprise-cloud@latest/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows)을 참조하세요. 사용하지 않도록 설정된 워크플로는 해당 트리거에 응답하지 않습니다.\n\n워크플로가 무엇에 의해 트리거될 것으로 예상되는지 이해하려면 워크플로의 `on:` 필드를 검토할 수 있습니다. 자세한 내용은 [워크플로우 시작](/ko/enterprise-cloud@latest/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow)을(를) 참조하세요.\n\n사용 가능한 이벤트의 전체 목록은 [워크플로를 트리거하는 이벤트](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/events-that-trigger-workflows)을(를) 참조하세요.\n\n### 이벤트 조건 트리거\n\n일부 트리거링 이벤트는 기본 분기에서만 실행됩니다(예: `issues`, `schedule`). 기본 분기 외부에 존재하는 워크플로 파일 버전은 이러한 이벤트에서 트리거되지 않습니다.\n\n병합 충돌이 있는 풀 리퀘스트가 있는 경우 워크플로는 `pull_request` 작업에서 실행되지 않습니다.\n\n원래 `push` 또는 `pull_request` 활동에서 트리거되었어야 하는 워크플로라도, 커밋 메시지에 스킵 주석이 포함되어 있으면 건너뜁니다. 자세한 내용은 [워크플로 실행 건너뛰기](/ko/enterprise-cloud@latest/actions/how-tos/manage-workflow-runs/skip-workflow-runs)을(를) 참조하세요.\n\n### 예상치 못한 시간에 실행되는 예약 워크플로\n\n예약된 이벤트는 워크플로 실행 부하가 많은 기간 동안 지연될 수 있습니다 GitHub Actions .\n\n높은 로드 시간에는 매 시간의 시작이 포함됩니다. 부하가 충분히 높으면 일부 대기 중인 작업이 드롭될 수 있습니다. 지연 가능성을 줄이려면 워크플로가 다른 시간에 실행되도록 예약합니다. 자세한 내용은 [워크플로를 트리거하는 이벤트](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule)을(를) 참조하세요.\n\n### 필터링 및 diff 제한\n\n특정 이벤트는 분기, 태그 및/또는 사용자 지정 가능한 경로로 필터링할 수 있습니다. 필터 조건이 워크플로를 필터링하도록 적용되면 워크플로 실행 생성이 건너뛰어집니다.\n\n필터에 특수 문자를 사용할 수 있습니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.\n\n경로 필터링의 경우, diff 평가가 처음 300개 파일로 제한됩니다. 변경된 파일 중 필터가 반환한 처음 300개 파일에 포함되지 않은 파일이 있으면 워크플로가 실행되지 않습니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/workflow-syntax#git-diff-comparisons)을(를) 참조하세요.\n\n## 워크플로 실행 문제 해결\n\n워크플로 실행은 워크플로가 트리거되고 워크플로 실행이 생성된 이후에 발생하는 모든 문제를 포함합니다.\n\n### 작업 조건 디버깅\n\n작업이 예상치 않게 건너뛰어졌거나, 건너뛰어질 것으로 예상했는데 실행된 경우, 표현식 평가를 확인하여 이유를 파악할 수 있습니다.\n\n1. 워크플로 실행에서 작업을 클릭합니다.\n2. 작업 메뉴에서 로그 보관 파일을 다운로드합니다.\n3. `JOB-NAME/system.txt` 파일을 엽니다.\n4. `Evaluating`, `Expanded`및 `Result` 선을 찾습니다.\n\n`Expanded` 라인은 `if` 조건에 대체된 실제 런타임 값을 보여주며, 이로 인해 식이 `true` 또는 `false`로 평가된 이유를 명확히 설명합니다.\n\n자세한 내용은 [작업 조건 식 로그 보기](/ko/enterprise-cloud@latest/actions/how-tos/monitor-workflows/view-job-condition-logs)을(를) 참조하세요.\n\n### 워크플로 취소\n\n[UI](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/workflow-cancellation) 또는 [API](/ko/enterprise-cloud@latest/rest/actions/workflow-runs?apiVersion=2022-11-28#cancel-a-workflow-run)를 통한 표준 취소가 예상대로 처리되지 않으면, 실행 중인 워크플로 작업(들)에 취소되지 않도록 만드는 조건문이 구성되어 있을 수 있습니다.\n\n이런 경우 API를 활용하여 실행을 강제로 취소할 수 있습니다. 자세한 내용은 [워크플로 실행에 대한 REST API 엔드포인트](/ko/enterprise-cloud@latest/rest/actions/workflow-runs?apiVersion=2022-11-28#force-cancel-a-workflow-run)을(를) 참조하세요.\n\n일반적인 원인으로는 취소 시에도 `always()`을(를) 반환하는 [](/ko/enterprise-cloud@latest/actions/reference/workflows-and-actions/expressions#status-check-functions)`true`를 사용하는 경우가 있습니다. 대안으로는 `cancelled()` 함수의 역(inverse)인 `${{ !cancelled() }}`을(를) 사용할 수 있습니다.\n\n자세한 내용은 [조건을 사용하여 작업 실행 제어](/ko/enterprise-cloud@latest/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions) 및 [워크플로 실행 취소](/ko/enterprise-cloud@latest/actions/how-tos/manage-workflow-runs/cancel-a-workflow-run)을(를) 참조하세요.\n\n## 실행기 문제 해결\n\n### 실행기 레이블 정의\n\nGitHub호스팅 러너는 [](/ko/enterprise-cloud@latest/actions/reference/runners/github-hosted-runners#standard-github-hosted-runners-for-public-repositories) 리포지토리에서 유지 관리되는 `actions/runner-images`을 활용합니다.\n\n대형 실행기 및 자체 호스팅 실행기에는 고유한 레이블 이름을 사용하는 것을 권장합니다. 레이블이 기존 미리 설정된 레이블 중 어느 것과라도 일치하면, 작업이 어떤 일치 실행기 옵션에서 실행될지 보장되지 않아 실행기 할당 문제가 발생할 수 있습니다.\n\n### 자체 호스팅 실행기\n\n자체 호스팅 실행기를 사용하는 경우 해당 활동을 보고 일반적인 문제를 진단할 수 있습니다.\n\n자세한 내용은 [자체 호스트형 실행기 모니터링 및 문제 해결](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot)을(를) 참조하세요.\n\n### 보안 스캐너가 탐지한 러너 IP 주소\n\nGitHub호스팅된 실행기는 공유 인프라에서 동적으로 할당된 IP 주소를 사용합니다. 이러한 IP 주소는 Meta API(예 `actions` : 키 및 `actions_macos` 키)를 통해 게시됩니다. 자세한 내용은 [메타 데이터에 대한 REST API 엔드포인트](/ko/enterprise-cloud@latest/rest/meta/meta#get-github-meta-information)을(를) 참조하세요.\n\n타사 위협 인텔리전스 서비스, IP 평판 스캐너 또는 방화벽 공급업체는 이러한 IP 주소를 \"악성\" 또는 \"의심스러운\"으로 플래그를 지정할 수 있습니다. 기본 인프라가 공유되므로 동일한 인프라의 다른 사용자의 활동은 이러한 주소에 할당된 평판 점수에 영향을 줄 수 있습니다.\n\nGitHub 는 타사 IP 평판 목록을 제어하지 않으며 정확도 또는 업데이트 빈도에 대해 언급할 수 없습니다. IP 주소가 GitHub에서 호스팅되는 실행기에 속하는지 확인하려면 Meta API에서 반환하는 IP 범위를 확인합니다.\n\nMicrosoft 소유 IP 주소에 대한 보안 문제가 있는 경우 MSRC([Microsoft 보안 대응 센터)](https://msrc.microsoft.com/report/) 보고합니다.\n\n## 네트워킹 문제 해결 제안\n\n다음을 포함하는 네트워크 문제에 대해서는 지원이 제한됩니다:\n\n* 사용자의 네트워크\n* 외부 네트워크\n* 타사 시스템\n* 일반적인 인터넷 연결\n\nGitHub의 실시간 플랫폼 상태를 보려면 [GitHub 상태](https://githubstatus.com/)를 확인하세요.\n\n그 외 네트워크 관련 문제의 경우, 조직의 네트워크 설정을 검토하고 액세스 중인 타사 서비스의 상태를 확인하세요. 문제가 지속되면 네트워크 관리자에게 추가 지원을 요청하는 것을 고려하세요.\n\n이 문제에 대해 잘 모르는 경우 문의하세요 GitHub 지원. 지원에 문의하는 방법에 대한 자세한 내용은 [GitHub 지원에 문의](/ko/enterprise-cloud@latest/support/contacting-github-support)을(를) 참조하세요.\n\n### DNS\n\nDNS(Domain Name System) 구성, 해석 또는 확인자 문제로 인해 문제가 발생할 수 있습니다. 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것을 권장합니다.\n\n### 방화벽\n\n방화벽에 의해 활동이 차단될 수 있습니다. 이 경우 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것이 좋습니다.\n\n### 프록시\n\n통신에 프록시를 사용할 때 활동이 실패할 수 있습니다. 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것이 좋은 습관입니다.\n\n프록시를 활용하도록 실행기 애플리케이션을 구성하는 방법에 대한 정보는 [실행기에서 프록시 서버 사용](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/use-proxy-servers)을(를) 참조하세요.\n\n### 서브넷\n\n가상 클라우드 제공자 또는 Docker 네트워크 내부 등, 사용 중인 서브넷 문제나 기존 네트워크와의 중복으로 문제가 발생할 수 있습니다. 이런 경우 네트워크 토폴로지와 사용 중인 서브넷을 검토하는 것을 권장합니다.\n\n### 인증서\n\n자체 서명 또는 사용자 지정 인증서 체인 및 인증서 저장소로 인해 문제가 발생할 수 있습니다. 사용 중인 인증서가 만료되지 않았고 현재 신뢰되는지 확인할 수 있습니다. 인증서는 `curl` 또는 유사한 도구로 검사할 수 있습니다. 또한 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받을 수 있습니다.\n\n### IP 목록\n\nIP 허용 목록 또는 차단 목록이 예상된 통신을 방해할 수 있습니다. 문제가 발생하면 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것이 좋습니다.\n\nGitHub 계정이 IP 허용 목록으로 구성된 경우 실행기에서 허용 목록에 포함되지 않은 IP 주소를 사용하는 경우 워크플로가 실패합니다. 이를 해결하려면 실행기의 IP 주소가 조직 또는 기업의 허용 목록에 추가되었는지 확인하세요. 자세한 내용은 [조직에 허용되는 IP 주소 관리](/ko/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) 및/또는 [IP 허용 목록을 사용하여 엔터프라이즈에 대한 네트워크 트래픽 제한](/ko/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list)을(를) 참조하세요.\n\nGitHub의 IP 주소(예: GitHub 호스팅 실행기에서 사용되는 IP 주소)에 대한 자세한 내용은 [GitHub IP 주소 정보](/ko/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses)을 참조하세요.\n\n고정 IP 주소는 GitHub호스팅 대형 실행기에서 사용할 수 있습니다. 자세한 내용은 [대형 런너 관리하기](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/larger-runners/manage-larger-runners)을 참조하세요.\n\n### 운영 체제 및 소프트웨어 애플리케이션\n\n방화벽 또는 프록시 외에도 추가 소프트웨어 패키지 설치와 같이 호스팅된 실행기에서 수행되는 GitHub사용자 지정으로 인해 통신이 중단될 수 있습니다. 사용 가능한 사용자 지정 옵션에 대한 정보는 [GitHub 호스팅 실행기 사용자 지정](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/github-hosted-runners/customize-runners)을(를) 참조하세요.\n\n* 자체 호스팅 실행기의 경우, 필요한 엔드포인트에 대한 자세한 내용은 [자체 호스팅 실행기 참조](/ko/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners)에서 알아보세요.\n\n* WireGuard 구성 도움말은 [WireGuard를 사용하여 네트워크 오버레이 만들기](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-wireguard)을(를) 참조하세요.\n\n* OpenID Connect(OIDC) 구성에 대한 자세한 내용은 [OIDC와 함께 API 게이트웨이 사용](/ko/enterprise-cloud@latest/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-oidc)을(를) 참조하세요.\n\n### GitHub 호스트 실행기를 위한 Azure 비공개 네트워킹\n\n구성된 Azure VNET(Virtual Network) 설정 내에서 GitHub 호스팅된 실행기를 사용하면 문제가 발생할 수 있습니다.\n\n문제 해결 조언은 문서의 [조직에서 GitHub이 호스팅하는 실행기를 위한 Azure 사설 네트워크 구성 문제해결](/ko/enterprise-cloud@latest/organizations/managing-organization-settings/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization) 또는 [엔터프라이즈용 GitHub 호스트 실행기를 위한 Azure 비공개 네트워크 구성 문제 해결](/ko/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise)."}