Runner Fleet - GitHub Actions 러너 관리자
Go Test Coverage Go Report Card
문서 (Docs): 中文 · Français · Deutsch · 한국어 · 日本語
Golang Echo를 사용하여 구축된 HTTP 관리 UI로, 하나의 장치에서 여러 개의 자체 호스팅(self-hosted) GitHub Actions 러너를 보고 관리할 수 있습니다. YAML 기반 설정이며 데이터베이스가 필요하지 않습니다.
Linux 전용 (linux/amd64, linux/arm64): 러너의 활성 상태(liveness)는 /proc에서 읽어옵니다. UI와 메시지는 6개 언어를 지원하며, 로그는 영어로 고정됩니다 — 사용자 가이드를 참조하십시오.
주요 특징 (Highlights)
-
데이터베이스 제로(Zero database): YAML 전용 설정으로 외부 종속성(external deps)이 없습니다. 이 설정 자체가 백업 역할을 하며 버전 관리가 쉽습니다.
-
웹 원스톱(Web one-stop): UI에서 러너를 추가, 등록, 시작/중지, 편집 및 검사할 수 있습니다 — SSH 접속이나 config.sh을 수동으로 실행할 필요가 없습니다. GitHub의 ./config.sh --url … --token …을 붙여넣기만 하면 양식이 자동으로 채워집니다. 이름과 디렉터리 충돌은 입력하는 동안 제안된 이름과 함께 표시됩니다.
-
컨테이너 우선(Container-first): Docker / docker-compose를 기본으로 제공합니다. 작업 중 Docker 실행을 위해 DinD와 호스트 소켓(host-socket)을 지원하며, 옵션 컨테이너 모드(컨테이너당 하나의 러너)를 통해 관리자가 라이프사이클과 상태를 소유합니다.
-
설정 드리프트는 보고만 하는 것이 아니라 복구됩니다: 이미지, 네트워크, 마운트 디렉터리, 작업 중 Docker 백엔드 및 에이전트 토큰은 모두 docker create 시점에 고정되므로, 설정을 편집해도 기존 컨테이너에 도달하지 않습니다. 관리자는 각 컨테이너를 현재 설정과 비교합니다 — 중지된(stopped) 러너는 다음 시작 시 재구축되며, 실행 중인(running) 러너는 정확한 차이점과 함께 플래그가 지정되고 요청할 때 재구축됩니다.
-
호스팅 CLI 기반 + 사용자 정의 이미지: 기본 이미지는 CLI 계층을 GitHub 호스팅 ubuntu-24.04와 일치시킵니다. examples/runner-images/ 및 러너별 container_image를 통해 Android / Node 등 다른 환경으로 확장할 수 있습니다.
-
스스로 복구하며, 실패 원인을 알려줍니다: 등록되었으나 중지된 러너는 부팅 후 약 15초 뒤에 시작되며 5분마다 재확인됩니다. 컨테이너 모드에서는 단순한 "알 수 없음(unknown)" 대신 구조화된 진단—오류 유형, 확인 명령어, 수정 명령어—을 반환하는 실패 프로브를 제공합니다.
-
관찰 가능(Observable): 배포에 대한 /ready 및 Prometheus /metrics, 러너별 등록 결과, 그리고 GitHub가 실제로 나열하는 내용과 UI를 동기화하는 선택적 PAT(Personal Access Token)를 제공합니다.
빠른 시작 (Quick start)
mkdir -p config runners && cp config.yaml.example config/config.yaml
sudo chown -R 1001:1001 config runners
...
자체 호스팅 러너는 비공개 저장소에만 사용해야 합니다. 공개 저장소의 풀 리퀘스트가 이 장치에서 코드를 실행할 수 있습니다. SECURITY.md를 참조하세요.
http://localhost:8080을 엽니다. 기본 이미지 태그는 안정화된 릴리스(예: v1.9.7)입니다. 더 많은 옵션(docker run, DinD, 컨테이너 모드, 'main' 또는 다른 태그 사용)은 사용자 가이드를 참조하세요. 프로브, Prometheus 메트릭 및 로깅: 운영(Operations) — GET /health (활성 상태), GET /ready (준비 상태), GET /metrics, GET /version.
두 가지 즉시 배포(copy-and-go deployments)가 examples/deploy/에 있습니다: standalone/(단일 컨테이너, 러너 프로세스는 Manager 내부에 위치 — docker run 또는 Compose 사용)와 fleet/(러너당 하나의 컨테이너, 이미지 및 툴체인 캐시는 공유하고 빌드 캐시는 격리).
문서 (Documentation)
- 사용자 가이드 — 배포, 구성, 러너 추가, 운영, 보안 및 문제 해결
- 배포 예시 (중국어) — 단일 컨테이너 및 다중 컨테이너 설정, 공유되는 캐시와 격리되는 캐시, 배포 시 주의사항
- 개발 및 빌드 — Go 빌드, 로컬 디버그, HTTP API, Makefile
- 변경 로그(Changelog) — 릴리스 기록 및 업그레이드 노트
기타 (Other)
CI, images 및 releases와 관련된 워크플로우는 .github/workflows 디렉터리에 있습니다.
본 프로젝트는 MIT 라이선스를 따르며, 자세한 내용은 LICENSE 파일을 참고하십시오.