{"meta":{"title":"워크플로 문제 해결","intro":"도구를 GitHub Actions 사용하여 워크플로를 디버그할 수 있습니다.","product":"GitHub Actions","breadcrumbs":[{"href":"/ko/actions","title":"GitHub Actions"},{"href":"/ko/actions/how-tos","title":"사용법"},{"href":"/ko/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/actions/how-tos/monitor-workflows/use-workflow-run-logs)을(를) 참조하세요.\n\n### 디버그 로깅 사용\n\n워크플로 로그가 워크플로, 작업 또는 단계가 예상대로 작동하지 않는 이유를 진단하기에 충분한 세부 정보를 제공하지 않는 경우 추가 디버그 로깅을 사용하도록 설정할 수 있습니다. 자세한 내용은 [디버그 로깅 활성화](/ko/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/actions/tutorials/store-and-share-data)에 대한 실행기 시간(분)과 스토리지가 포함됩니다. 자세한 내용은 [GitHub Actions 비용 청구](/ko/billing/concepts/product-billing/github-actions)을(를) 참조하세요.\n\n### 예산 설정\n\n작업 예산을 설정하면 청구 또는 스토리지 오류로 인해 실패하는 워크플로를 즉시 차단 해제하는 데 도움이 될 수 있습니다. 설정된 예산 금액까지 추가 시간(분)과 스토리지 사용량이 청구되도록 허용합니다. 자세한 내용은 [예산을 설정하여 요금제 제품에 대한 지출을 제어합니다.](/ko/billing/how-tos/set-up-budgets)를 참조하세요.\n\n## 메트릭을 사용하여 작업 검토 GitHub Actions\n\n메트릭을 사용하여 워크플로의 효율성과 안정성을 분석하는 방법은 [GitHub Actions 메트릭 보기](/ko/actions/how-tos/administer/view-metrics)을(를) 참조하세요.\n\n## 워크플로 트리거 문제 해결\n\n먼저 워크플로를 수동으로 사용하지 않도록 설정하지 않았는지 확인합니다. [워크플로를 사용/사용하지 않도록 설정](/ko/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows)을 참조하세요. 사용하지 않도록 설정된 워크플로는 해당 트리거에 응답하지 않습니다.\n\n워크플로가 무엇에 의해 트리거될 것으로 예상되는지 이해하려면 워크플로의 `on:` 필드를 검토할 수 있습니다. 자세한 내용은 [워크플로우 시작](/ko/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow)을(를) 참조하세요.\n\n사용 가능한 이벤트의 전체 목록은 [워크플로를 트리거하는 이벤트](/ko/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/actions/how-tos/manage-workflow-runs/skip-workflow-runs)을(를) 참조하세요.\n\n### 예상치 못한 시간에 실행되는 예약 워크플로\n\n예약된 이벤트는 워크플로 실행 부하가 많은 기간 동안 지연될 수 있습니다 GitHub Actions .\n\n높은 로드 시간에는 매 시간의 시작이 포함됩니다. 부하가 충분히 높으면 일부 대기 중인 작업이 드롭될 수 있습니다. 지연 가능성을 줄이려면 워크플로가 다른 시간에 실행되도록 예약합니다. 자세한 내용은 [워크플로를 트리거하는 이벤트](/ko/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule)을(를) 참조하세요.\n\n### 필터링 및 diff 제한\n\n특정 이벤트는 분기, 태그 및/또는 사용자 지정 가능한 경로로 필터링할 수 있습니다. 필터 조건이 워크플로를 필터링하도록 적용되면 워크플로 실행 생성이 건너뛰어집니다.\n\n필터에 특수 문자를 사용할 수 있습니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet)을(를) 참조하세요.\n\n경로 필터링의 경우, diff 평가가 처음 300개 파일로 제한됩니다. 변경된 파일 중 필터가 반환한 처음 300개 파일에 포함되지 않은 파일이 있으면 워크플로가 실행되지 않습니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/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/actions/how-tos/monitor-workflows/view-job-condition-logs)을(를) 참조하세요.\n\n### 워크플로 취소\n\n[UI](/ko/actions/reference/workflows-and-actions/workflow-cancellation) 또는 [API](/ko/rest/actions/workflow-runs?apiVersion=2022-11-28#cancel-a-workflow-run)를 통한 표준 취소가 예상대로 처리되지 않으면, 실행 중인 워크플로 작업(들)에 취소되지 않도록 만드는 조건문이 구성되어 있을 수 있습니다.\n\n이런 경우 API를 활용하여 실행을 강제로 취소할 수 있습니다. 자세한 내용은 [워크플로 실행에 대한 REST API 엔드포인트](/ko/rest/actions/workflow-runs?apiVersion=2022-11-28#force-cancel-a-workflow-run)을(를) 참조하세요.\n\n일반적인 원인으로는 취소 시에도 `always()`을(를) 반환하는 [](/ko/actions/reference/workflows-and-actions/expressions#status-check-functions)`true`를 사용하는 경우가 있습니다. 대안으로는 `cancelled()` 함수의 역(inverse)인 `${{ !cancelled() }}`을(를) 사용할 수 있습니다.\n\n자세한 내용은 [조건을 사용하여 작업 실행 제어](/ko/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions) 및 [워크플로 실행 취소](/ko/actions/how-tos/manage-workflow-runs/cancel-a-workflow-run)을(를) 참조하세요.\n\n## 실행기 문제 해결\n\n### 실행기 레이블 정의\n\nGitHub호스팅 러너는 [](/ko/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/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/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/support/contacting-github-support)을(를) 참조하세요.\n\n### DNS\n\nDNS(Domain Name System) 구성, 해석 또는 확인자 문제로 인해 문제가 발생할 수 있습니다. 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것을 권장합니다.\n\n### 방화벽\n\n방화벽에 의해 활동이 차단될 수 있습니다. 이 경우 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것이 좋습니다.\n\n### 프록시\n\n통신에 프록시를 사용할 때 활동이 실패할 수 있습니다. 사용 가능한 로그를 검토하거나 공급업체 문서를 확인하거나 관리자와 상의하여 추가 지원을 받는 것이 좋은 습관입니다.\n\n프록시를 활용하도록 실행기 애플리케이션을 구성하는 방법에 대한 정보는 [실행기에서 프록시 서버 사용](/ko/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 주소(예: GitHub 호스팅 실행기에서 사용되는 IP 주소)에 대한 자세한 내용은 [GitHub IP 주소 정보](/ko/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses)을 참조하세요.\n\n고정 IP 주소는 GitHub호스팅 대형 실행기에서 사용할 수 있습니다. 자세한 내용은 [대형 런너 관리하기](/ko/actions/how-tos/manage-runners/larger-runners/manage-larger-runners)을 참조하세요.\n\n### 운영 체제 및 소프트웨어 애플리케이션\n\n방화벽 또는 프록시 외에도 추가 소프트웨어 패키지 설치와 같이 호스팅된 실행기에서 수행되는 GitHub사용자 지정으로 인해 통신이 중단될 수 있습니다. 사용 가능한 사용자 지정 옵션에 대한 정보는 [GitHub 호스팅 실행기 사용자 지정](/ko/actions/how-tos/manage-runners/github-hosted-runners/customize-runners)을(를) 참조하세요.\n\n* 자체 호스팅 실행기의 경우, 필요한 엔드포인트에 대한 자세한 내용은 [자체 호스팅 실행기 참조](/ko/actions/reference/runners/self-hosted-runners)에서 알아보세요.\n\n* WireGuard 구성 도움말은 [WireGuard를 사용하여 네트워크 오버레이 만들기](/ko/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-wireguard)을(를) 참조하세요.\n\n* OpenID Connect(OIDC) 구성에 대한 자세한 내용은 [OIDC와 함께 API 게이트웨이 사용](/ko/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/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) 을 GitHub Enterprise Cloud 참조하세요."}