자체 호스팅 러너 모니터링 및 문제 해결

자체 호스팅 러너를 모니터링해 활동을 보고 일반적인 문제를 진단할 수 있어요. 러너 상태 확인, 네트워크 연결 문제 해결, 로그 파일 검토, 자동 업데이트 모니터링 방법을 살펴봐요.

출처: 문서

본문

접근 수준 확인하기

조직 소유 저장소에 대해 자체 호스팅 러너를 만들지 못할 수 있어요.

조직 소유자는 저장소 수준 자체 호스팅 러너를 만들 수 있는 저장소를 선택할 수 있어요.

자세한 내용은 조직의 GitHub Actions 비활성화 또는 제한하기를 참고하세요.

자체 호스팅 러너 상태 확인하기

자체 호스팅 러너는 GitHub 설정의 저장소, 조직, 또는 엔터프라이즈 계정 어디에나 위치할 수 있어요. 자체 호스팅 러너를 관리하려면 러너가 추가된 위치에 따라 다음 권한이 있어야 해요:

사용자 저장소: 저장소 소유자여야 해요.
조직: 조직 소유자여야 해요.
조직 저장소: 조직 소유자이거나 저장소에 대한 admin 접근 권한이 있어야 해요.

조직이나 저장소에서 메인 페이지로 이동해 설정 아이콘(기어)을 클릭해요.
왼쪽 사이드바에서 Actions을 클릭한 다음 Runners을 클릭해요.
"Runners" 아래에서 등록된 러너 목록(러너 이름, 레이블, 상태 포함)을 볼 수 있어요.

상태는 다음 중 하나일 수 있어요:
- Idle: 러너가 GitHub에 연결되어 작업을 실행할 준비가 되었어요.
- Active: 러너가 현재 작업을 실행 중이에요.
- Offline: 러너가 GitHub에 연결되어 있지 않아요. 머신이 오프라인이거나, 자체 호스팅 러너 애플리케이션이 머신에서 실행되지 않거나, 자체 호스팅 러너 애플리케이션이 GitHub와 통신할 수 없기 때문일 수 있어요.

네트워크 연결 문제 해결

자체 호스팅 러너 네트워크 연결 확인하기

자체 호스팅 러너 애플리케이션의 config 스크립트를 --check 파라미터와 함께 사용해 자체 호스팅 러너가 GitHub의 모든 필수 네트워크 서비스에 접근할 수 있는지 확인할 수 있어요.

--check 외에도 스크립트에 두 인자를 제공해야 해요:

--url에 GitHub 저장소, 조직, 또는 엔터프라이즈의 URL을 넣어요. 예: --url https://github.com/octo-org/octo-repo.
--pat에 workflow 스코프가 있어야 하는 개인 액세스 토큰(classic)의 값, 또는 워크플로 읽기·쓰기 접근이 있는 세밀한 개인 액세스 토큰을 넣어요. 예: --pat ghp_abcd1234. 자세한 내용은 개인 액세스 토큰 관리하기를 참고하세요.

예를 들어:

macOS / Linux:

./config.sh --check --url URL --pat «redacted:ghp_…»

Windows:

config.cmd --check --url https://github.com/YOUR-ORG/YOUR-REPO --pat GHP_ABCD1234

스크립트는 각 서비스를 테스트하고 각각 PASS 또는 FAIL을 출력해요. 실패한 검사가 있다면 검사에 대한 로그 파일에서 문제에 대한 더 자세한 내용을 볼 수 있어요. 로그 파일은 러너 애플리케이션을 설치한 _diag 디렉토리에 있으며, 각 검사에 대한 로그 파일의 경로는 스크립트의 콘솔 출력에 표시돼요.

실패한 검사가 있다면 자체 호스팅 러너 머신이 모든 통신 요구 사항을 충족하는지도 확인해야 해요. 자세한 내용은 자체 호스팅 러너 참조를 참고하세요.

TLS 인증서 검증 비활성화하기

기본적으로 자체 호스팅 러너 애플리케이션은 GitHub의 TLS 인증서를 검증해요. 네트워크 문제가 발생하면 테스트 목적으로 TLS 인증서 검증을 비활성화하고 싶을 수 있어요.

자체 호스팅 러너 애플리케이션에서 TLS 인증서 검증을 비활성화하려면, 자체 호스팅 러너 애플리케이션을 구성·실행하기 전에 GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY 환경 변수를 1로 설정해요.

Linux / macOS:

export GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY=1
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO --token
./run.sh

Windows:

[Environment]::SetEnvironmentVariable('GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY', '1')
./config.cmd --url https://github.com/YOUR-ORG/YOUR-REPO --token
./run.cmd

Warning

TLS는 자체 호스팅 러너 애플리케이션과 GitHub 사이에 개인 정보 보호와 데이터 무결성을 제공하므로 TLS 검증을 비활성화하는 것은 권장하지 않아요. 자체 호스팅 러너의 운영 체제 인증서 저장소에 GitHub 인증서를 설치할 것을 권장해요. GitHub 인증서 설치 방법에 대한 지침은 운영 체제 공급업체에 문의하세요.

Note

Azure 사설 네트워킹을 사용하는 GitHub 호스팅 더 큰 러너의 경우 조직에서 GitHub 호스팅 러너의 사설 네트워킹 구성하기의 TLS 가로채기 요구 사항을 참고하세요.

자체 호스팅 러너 애플리케이션 로그 파일 검토하기

자체 호스팅 러너 애플리케이션의 상태와 활동을 모니터링할 수 있어요. 로그 파일은 러너 애플리케이션을 설치한 _diag 디렉토리에 보관되며, 애플리케이션이 시작될 때마다 새 로그가 생성돼요. 파일 이름은 Runner_로 시작하고, 애플리케이션이 시작된 UTC 타임스탬프가 뒤따라요.

Warning

임시(ephemeral) 러너의 러너 애플리케이션 로그 파일은 문제 해결과 진단 목적으로 외부에 전달·보존되어야 해요. 임시 러너와 자동 확장 자체 호스팅 러너에 대한 자세한 내용은 자체 호스팅 러너 참조를 참고하세요.

워크플로 작업 실행에 대한 상세 로그는 Worker_ 파일을 설명하는 다음 섹션을 참고하세요.

작업 로그 파일 검토하기

자체 호스팅 러너 애플리케이션은 처리하는 각 작업에 대해 상세 로그 파일을 만들어요. 이 파일들은 러너 애플리케이션을 설치한 _diag 디렉토리에 저장되며, 파일 이름은 Worker_로 시작해요.

(Linux) journalctl로 자체 호스팅 러너 애플리케이션 서비스 확인하기

서비스를 사용해 애플리케이션을 실행하는 Linux 기반 자체 호스팅 러너의 경우 journalctl을 사용해 실시간 활동을 모니터링할 수 있어요. 기본 systemd 기반 서비스는 actions.runner.<org>-<repo>.<runnerName>.service 명명 규칙을 사용해요. 이 이름은 80자를 초과하면 잘리므로, 서비스 이름을 찾는 권장 방법은 .service 파일을 확인하는 것이에요. 예를 들어:

$ cat ~/actions-runner/.service
actions.runner.octo-org-octo-repo.runner01.service

서비스가 다른 곳에 설치되어 이 방법이 실패하면 실행 중인 서비스 목록에서 서비스 이름을 찾을 수 있어요. 예를 들어 대부분의 Linux 시스템에서 systemctl 명령을 사용할 수 있어요:

$ systemctl --type=service | grep actions.runner
actions.runner.octo-org-octo-repo.hostname.service loaded active running GitHub Actions Runner (octo-org-octo-repo.hostname)

journalctl을 사용해 자체 호스팅 러너의 실시간 활동을 모니터링할 수 있어요:

sudo journalctl -u actions.runner.octo-org-octo-repo.runner01.service -f

이 예제 출력에서 runner01이 시작되고, testAction이라는 작업을 받고, 결과 상태를 표시하는 것을 볼 수 있어요:

Feb 11 14:57:07 runner01 runsvc.sh[962]: Starting Runner listener with startup type: service
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started listener process
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started running service
Feb 11 14:57:16 runner01 runsvc.sh[962]: √ Connected to GitHub
Feb 11 14:57:17 runner01 runsvc.sh[962]: 2020-02-11 14:57:17Z: Listening for Jobs
Feb 11 16:06:54 runner01 runsvc.sh[962]: 2020-02-11 16:06:54Z: Running job: testAction
Feb 11 16:07:10 runner01 runsvc.sh[962]: 2020-02-11 16:07:10Z: Job testAction completed with result: Succeeded

systemd 구성을 보려면 여기에서 서비스 파일을 찾을 수 있어요: /etc/systemd/system/actions.runner.<org>-<repo>.<runnerName>.service. 자체 호스팅 러너 애플리케이션 서비스를 커스터마이징하고 싶다면 이 파일을 직접 수정하지 마세요. 자체 호스팅 러너 애플리케이션을 서비스로 구성하기에 설명된 지침을 따르세요.

(macOS) `launchd`로 자체 호스팅 러너 애플리케이션 서비스 확인하기

서비스로 애플리케이션을 실행하는 macOS 기반 자체 호스팅 러너의 경우 launchctl을 사용해 실시간 활동을 모니터링할 수 있어요. 기본 launchd 기반 서비스는 actions.runner.<org>-<repo>.<runnerName> 명명 규칙을 사용해요. 이 이름은 80자를 초과하면 잘리므로, 서비스 이름을 찾는 권장 방법은 러너 디렉토리의 .service 파일을 확인하는 것이에요:

% cat ~/actions-runner/.service
/Users/exampleUsername/Library/LaunchAgents/actions.runner.octo-org-octo-repo.runner01.plist

svc.sh 스크립트는 launchctl을 사용해 애플리케이션이 실행 중인지 확인해요. 예를 들어:

$ ./svc.sh status
status actions.runner.example.runner01:
/Users/exampleUsername/Library/LaunchAgents/actions.runner.example.runner01.plist
Started:
379 0 actions.runner.example.runner01

결과 출력에는 프로세스 ID와 애플리케이션의 launchd 서비스 이름이 포함돼요.

launchd 구성을 보려면 여기에서 서비스 파일을 찾을 수 있어요: /Users/exampleUsername/Library/LaunchAgents/actions.runner.<repoName>.<runnerName>.service. 자체 호스팅 러너 애플리케이션 서비스를 커스터마이징하고 싶다면 이 파일을 직접 수정하지 마세요. 자체 호스팅 러너 애플리케이션을 서비스로 구성하기에 설명된 지침을 따르세요.

(Windows) PowerShell로 자체 호스팅 러너 애플리케이션 서비스 확인하기

서비스로 애플리케이션을 실행하는 Windows 기반 자체 호스팅 러너의 경우 PowerShell을 사용해 실시간 활동을 모니터링할 수 있어요. 서비스는 GitHub Actions Runner (<org>-<repo>.<runnerName>) 명명 규칙을 사용해요. 러너 디렉토리의 .service 파일을 확인해 서비스 이름을 찾을 수도 있어요:

PS C:\actions-runner> Get-Content .service
actions.runner.octo-org-octo-repo.runner01.service

Windows Services 애플리케이션(services.msc)에서 러너의 상태를 볼 수 있어요. PowerShell을 사용해 서비스가 실행 중인지 확인할 수도 있어요:

PS C:\actions-runner> Get-Service "actions.runner.octo-org-octo-repo.runner01.service" | Select-Object Name, Status
Name                                                  Status
----                                                  ------
actions.runner.octo-org-octo-repo.runner01.service    Running

PowerShell을 사용해 자체 호스팅 러너의 최근 활동을 확인할 수 있어요. 이 예제 출력에서 애플리케이션이 시작되고, testAction이라는 작업을 받고, 결과 상태를 표시하는 것을 볼 수 있어요:

PS C:\actions-runner> Get-EventLog -LogName Application -Source ActionsRunnerService

   Index Time          EntryType   Source                 InstanceID Message
   ----- ----          ---------   ------                 ---------- -------
     136 Mar 17 13:45  Information ActionsRunnerService          100 2020-03-17 13:45:48Z: Job Greeting completed with result: Succeeded
     135 Mar 17 13:45  Information ActionsRunnerService          100 2020-03-17 13:45:34Z: Running job: testAction
     134 Mar 17 13:41  Information ActionsRunnerService          100 2020-03-17 13:41:54Z: Listening for Jobs
     133 Mar 17 13:41  Information ActionsRunnerService          100 √ Connected to GitHub
     132 Mar 17 13:41  Information ActionsRunnerService            0 Service started successfully.
     131 Mar 17 13:41  Information ActionsRunnerService          100 Starting Actions Runner listener
     130 Mar 17 13:41  Information ActionsRunnerService          100 Starting Actions Runner Service
     129 Mar 17 13:41  Information ActionsRunnerService          100 create event log trace source for actions-runner service

자동 업데이트 프로세스 모니터링하기

자체 호스팅 러너는 특정 버전 임계값 아래로 내려가면 작업을 처리할 수 없으므로, 자동 업데이트 프로세스를 정기적으로 확인할 것을 권장해요. 자체 호스팅 러너 애플리케이션은 자동으로 업데이트되지만, 이 프로세스에는 운영 체제나 다른 소프트웨어에 대한 업데이트는 포함되지 않아요. 이러한 업데이트는 별도로 관리해야 해요.

Runner_ 로그 파일에서 업데이트 활동을 볼 수 있어요. 예를 들어:

[Feb 12 12:37:07 INFO SelfUpdater] An update is available.

또한 러너 애플리케이션을 설치한 _diag 디렉토리에 있는 SelfUpdate 로그 파일에서 더 많은 정보를 찾을 수 있어요.

(Linux) 자체 호스팅 러너의 컨테이너 문제 해결

Docker가 설치되어 있는지 확인하기

작업에 컨테이너가 필요하다면 자체 호스팅 러너는 Linux 기반이어야 하고 Docker가 설치되어 있어야 해요. 자체 호스팅 러너에 Docker가 설치되어 있고 서비스가 실행 중인지 확인하세요.

systemctl을 사용해 서비스 상태를 확인할 수 있어요:

$ sudo systemctl is-active docker.service
active

Docker가 설치되지 않았다면 종속 액션들이 다음 오류로 실패해요:

[2020-02-13 16:56:10Z INFO DockerCommandManager] Which: 'docker'
[2020-02-13 16:56:10Z INFO DockerCommandManager] Not found.
[2020-02-13 16:56:10Z ERR  StepsRunner] Caught exception from step: System.IO.FileNotFoundException: File not found: 'docker'

Docker 권한 확인하기

작업이 다음 오류로 실패하면:

dial unix /var/run/docker.sock: connect: permission denied

자체 호스팅 러너의 서비스 계정이 Docker 서비스를 사용할 권한이 있는지 확인하세요. systemd에서 자체 호스팅 러너 구성을 확인해 이 계정을 식별할 수 있어요. 예를 들어:

$ sudo systemctl show -p User actions.runner.octo-org-octo-repo.runner01.service
User=runner-user

러너에 어떤 Docker 엔진이 설치되어 있는지 확인하기

빌드가 다음 오류로 실패하면:

Error: Input required and not supplied: java-version

자체 호스팅 러너에 어떤 Docker 엔진이 설치되어 있는지 확인하세요. 액션의 입력을 Docker 컨테이너로 전달하기 위해 러너는 이름의 일부로 대시가 포함될 수 있는 환경 변수를 사용해요. Docker 엔진이 바이너리 실행 파일이 아니라 셸 래퍼나 링크(예: Linux에서 snap으로 설치된 Docker 엔진)라면 액션이 입력을 얻지 못할 수 있어요. 이 오류를 해결하려면 자체 호스팅 러너가 다른 Docker 엔진을 사용하도록 구성해요.

Docker 엔진이 snap으로 설치되었는지 확인하려면 which 명령을 사용하세요. 다음 예제에서 Docker 엔진은 snap으로 설치되었어요:

$ which docker
/snap/bin/docker

자체 호스팅 러너 모니터링 및 문제 해결