AI Harness Sync

배경

AI Harness Sync는 여러 프로젝트에서 사용하는 에이전트·스킬·훅 등 AI 개발 환경 설정을 중앙 저장소에서 관리하고, 각 레포지토리가 필요한 항목을 골라 자동으로 동기화하는 시스템입니다. 60개 이상의 레포지토리에서 사용하고 있습니다. 레포마다 설정을 따로 복사해 관리하면 개선 사항이 늦게 퍼지고 레포 간 설정이 어긋납니다. 한 곳에서 고치면 모든 레포에 반영되도록 하는 것이 이 시스템의 목적입니다.

처음에는 팀 내부에서만 쓰던 하네스 설정을 관리하는 용도였습니다. 외부 사용자까지 쓰게 되면서 최신 설정이 늦게 반영되고, 개발진이 요청을 하나하나 손으로 처리해야 하는 문제가 생겼습니다. 이를 해결하려고 GitHub App 기반 관리 대시보드를 만들었고, 이 대시보드가 제가 맡은 부분입니다. 동기화 자체는 GitHub Actions가 수행하고, 대시보드는 설정을 확인·변경하고 즉시 동기화를 요청하는 창구입니다.

맡은 일

대시보드를 기획·설계하고, 설정 관리·즉시 동기화·가이드 기능을 프론트엔드와 백엔드 모두 구현했습니다. PR 8개를 머지했고, 그중 #12–#15가 대시보드의 공통 기반과 주요 기능입니다.

한 일

GitHub 권한을 분리한 대시보드 기반

• 문제: 설치된 저장소와 사용자의 변경 권한을 확인하면서, 서버가 설정 파일을 변경하고 PR을 만들 수 있는 인증 구조가 필요했습니다.
• 해결: GitHub OAuth 사용자 토큰으로 로그인 사용자와 저장소 권한을 확인하고, 실제 저장소 변경에는 GitHub App 설치 토큰을 사용하도록 인증 책임을 분리했습니다. 대시보드 기반·인증·저장소 조회 API를 구성했습니다. #12
• 결과: 권한 확인과 앱의 저장소 쓰기 작업을 구분한 상태에서 대시보드가 설정 조회·변경 기능을 제공하게 됐습니다.

선택한 하네스 설정을 PR로 관리

• 문제: 프로젝트별 선택 설정을 YAML을 직접 편집하지 않고 확인·수정할 수 있어야 했습니다.
• 해결: sync-manifest.yml과 대상 레포의 .harness/sync.yml을 읽어 항목 선택과 YAML 변경 미리보기를 제공하고, 변경은 대상 레포에 설정 PR로 생성했습니다. 별도 데이터베이스를 설정 원본으로 두지 않고 GitHub 저장소의 파일을 기준으로 삼았습니다. #13
• 결과: 설정 변경 내용을 PR로 검토하는 흐름을 대시보드에 연결했습니다. Vitest 테스트에는 선택 설정 생성, YAML diff, 권한 없는 조회, 열린 설정 PR 및 변경 없음 처리 사례가 포함됩니다.

레포지토리 단위 즉시 동기화

• 문제: 설정 반영을 정기 실행이나 운영진의 수동 요청에 의존하면 대상 레포가 최신 설정을 받기까지 지연될 수 있었습니다.
• 해결: 대시보드에서 선택한 레포만 workflow_dispatch로 요청하도록 API와 버튼을 추가하고, workflow 입력에 대상 레포를 전달했습니다. 중복 방지를 위해 열린 동기화 PR과 실행 중인 workflow를 확인하고 레포별 실행을 직렬화했습니다. #14
• 결과: 최신 설정 반영 시간이 최대 하루에서 약 1분으로 줄었습니다. 대시보드에서 동기화 비활성화 레포를 실행하지 않는 API 테스트와 요청 버튼 테스트도 추가했습니다.