gh-aw-fleet 소개

저는 몇 달 전부터 GitHub Agentic Workflows를 사용하기 시작했습니다. 이는 코드 리뷰, 일일 문서 업데이트, 악성 코드 스캔 및 PR 수정 등을 위해 CI 내에서 실행되는 작고 클로드(Claude)/코파일럿(Copilot) 에이전트입니다. 작성자는 이를 마크다운으로 작성하고, GitHub Actions로 컴파일되며, AI 에이전트가 각 실행마다 작업을 수행합니다.

몇 개의 레포지토리를 작동시키면서 다음과 같은 질문에 부딪혔습니다. 제가 실제로 각각의 레포지토리에서 무엇이 배포되고 있는지 어떻게 추적할 수 있을까요? 어떤 버전일까요? 어떤 프로필을 사용하고 있을까요? 어디서 '드리프트(drift)'가 발생했을까요?

그래서 저는 하나의 도구를 만들었습니다.

이것은 무엇인가요

gh-aw-fleet은 GitHub Agentic Workflows를 위한 선언적 플릿 매니저입니다. 하나의 fleet.json 파일이 레포지토리와 해당 워크플로우가 가져야 할 '프로필'을 선언하며, CLI는 이를 조정(reconcile)합니다 (deploy, sync, upgrade, add). 기본적으로 모든 작업은 건조 실행(dry-run)으로 이루어집니다. 이는 gh aw, gh, 그리고 git 주변의 얇은 오케스트레이터일 뿐, 포크(fork)가 아닙니다.

이 도구는 워크플로우 마크다운을 절대 재작성하지 않습니다. 단지 (누가 어떤 워크플로우를 언제, 어느 프로필로부터 가져야 하는지)에 대한 질문에 답하고 실제 파일 작업은 gh aw로 디스패치합니다. 레포지토리를 건드리는 모든 작업은 그곳에 PR을 열게 됩니다. 절대 force-push를 하거나 main 브랜치에 커밋하지 않습니다.

# 전체 플릿의 드리프트를 확인하며, 클론 없이 읽기 전용으로 실행
gh-aw-fleet status

...

건조 실행(dry-run) 게이트는 제가 가장 의존하는 부분입니다. deploy, sync, 그리고 upgrade는 --apply를 추가하기 전까지 정확히 무엇을 할지 출력할 뿐 아무것도 변경하지 않습니다. 한 번에 수십 개의 레포지토리를 다룰 때,

출시 이후 업데이트된 사항

v0.1.0 버전은 핵심적인 리컨사일 루프 (reconcile loop)와 함께 4월 21일에 출시되었습니다. 현재 v0.2.0 버전이며, 그동안의 차이점은 주로 더 많은 레포지토리 (repos)에 대해 이 도구를 신뢰할 수 있도록 만드는 데 집중되었습니다.

• status / 드리프트 탐지 (drift detection): 아무것도 클론 (cloning)하지 않고도 전체 플릿 (fleet)에서 일치하지 않는 부분을 확인하고, 이를 기반으로 CI 작업을 제어할 수 있습니다.
• JSON 출력 + 구조화된 로깅 (structured logging): 읽기 명령에 -o json을 지원하며, 내부적으로 zerolog를 사용하여 결과를 jq나 애그리게이터 (aggregator)로 파이프 (pipe)할 수 있습니다.
• 재개 가능한 배포 (resumable deploys): 배포가 중간에 중단되었을 때 처음부터 다시 시작하는 대신, 커밋 (commit) 또는 푸시 (push) 게이트에서 중단된 지점부터 다시 시작할 수 있습니다.
• Layer-1 보안 스캐너 (security scanner): 무언가가 배포되기 전에 비밀값 (secrets)과 구조적 규칙을 검사합니다.
• observability-plus 프로필 + HTTP 402 과금 진단 (billing diagnostic): 위에서 언급한 과금 기능 구현을 위한 초기 기반 작업입니다.
• HuJSON 설정: fleet.json에서 주석과 트레일링 콤마 (trailing commas)를 지원하여, 핀 (pin) 설정 바로 옆에 해당 핀을 설정한 이유를 문서화할 수 있습니다.

현재 상태

v0.2.0 버전으로, 아직 1.0 미만 단계입니다. 따라서 CLI 플래그 (flags)와 fleet.json 스키마 (schema)는 1.0 버전 이전에 변경될 수 있습니다. 하지만 저는 이미 제 개인 레포지토리들을 관리하는 데 이 도구를 사용하고 있으며, 매우 잘 작동하고 있습니다.

• Repo + docs
• Latest release