예약 실행 코딩 에이전트: 스모크 테스트와 머지 큐를 통한 병합

코딩 에이전트의 야간 작업을 예약하고, 격리된 환경에서 실행한 뒤, 스모크 테스트와 사람의 검토를 거쳐 머지 큐로 병합하는 절차를 살펴본다.

개정 2판 · 최근 고침: 독자에게 보이는 문장과 용어를 다듬고 기존 근거 연결을 유지했다. · 고침 기록 보기

예약 실행의 동작과 격리·검토 원칙을 설명한다. 재시도 정책과 에이전트에 맡길 작업의 범위는 각 팀이 정해야 한다. 아래 새벽 작업 사례는 실행하지 않은 가상 예시이며 속도나 성능 측정값을 제시하지 않는다.

밤사이 맡긴 작업은 어디까지 진행됐을까

코딩 에이전트에 밤사이 일을 맡기고 아침에 결과를 검토할 수 있다면 편리할 것이다. 하지만 실제로 확인할 상태는 여러 가지다. 작업이 시작되지 않았거나 중간에 멈췄을 수 있고, 수정안을 만들었더라도 검증이 끝나지 않았거나 병합 순서를 기다리고 있을 수 있다.

야간 자동화에는 예약, 실행 환경, 스모크 테스트, 풀 리퀘스트 검토, 머지 큐의 병합이 차례로 연결된다. 예약은 정시 실행을 보장하지 않으며 각 단계에서도 작업이 멈출 수 있다. 다음 날 결과를 확인하려면 단계별 동작과 기록을 알아야 한다.

이 절의 근거 S36 · S38 · S32 · S33 · S34

예약 시각과 실제 실행 시각은 다를 수 있다

GitHub Actions의 schedule은 다섯 필드로 된 POSIX cron 형식으로 실행 시각을 정한다. 기본 시간대는 UTC이며 다른 시간대를 선택할 수도 있다. 가장 짧은 실행 간격은 5분이다. 예약 워크플로는 기본 브랜치의 최신 커밋에서 실행된다.

예약 시각에 실행된다는 보장은 없다. 실행이 몰리면 지연될 수 있고, 부하가 크면 대기 작업이 삭제될 수도 있다고 문서는 설명한다. 매시 정각처럼 실행이 몰리는 시간은 피하는 편이 좋다. 예약 워크플로는 기본 브랜치에서만 실행되며, 공개 저장소에서 60일 동안 활동이 없으면 자동으로 비활성화된다. 작업이 늦거나 누락될 때 후속 절차를 어떻게 처리할지도 정해야 한다.

이 절의 근거 S36

러너 선택과 실행 환경 격리

작업은 러너에서 실행된다. GitHub가 제공하는 러너도 있고, 팀이 직접 두는 셀프호스티드 러너도 있다. 셀프호스티드 러너는 저장소·조직·기업 단위로 등록할 수 있으며, 먼저 실행할 기계에 접근할 수 있어야 한다.

러너를 선택할 때는 보안 조건도 살펴야 한다. 포크한 공개 저장소의 풀 리퀘스트가 셀프호스티드 러너에서 위험한 코드를 돌릴 수 있으므로, 셀프호스티드 러너는 비공개 저장소에만 쓰라고 권한다. 신뢰할 수 없는 코드가 시크릿과 러너에 접근하면 보안 사고가 생길 수 있다. 어떤 시크릿과 권한을 제공하고, 실패한 실행 환경을 어떻게 정리할지를 정하는 일은 팀의 설계 몫이다. 필요한 격리 수준은 팀이 정해야 한다.

이 절의 근거 S37

스모크 테스트로 핵심 동작 먼저 확인하기

스모크 테스트는 밤사이 수정한 코드의 핵심 동작을 적은 비용으로 빠르게 확인하는 방법이다. Playwright의 프로젝트는 같은 설정을 공유하는 테스트 묶음이다. 브라우저, 기기, 로그인 상태, 실행 환경, 타임아웃과 재시도를 프로젝트마다 다르게 설정하고 전체 또는 특정 프로젝트만 실행할 수 있다. 문서의 예시에서는 Smoke 프로젝트가 작은 테스트 집합을 재시도 없이 실행하고 기본 프로젝트가 나머지를 재시도와 함께 실행한다.

로그인 같은 준비 작업은 setup 프로젝트로 분리하고 프로젝트 의존성을 설정해 먼저 실행할 수 있다. 스모크 테스트는 선택한 핵심 경로가 기대대로 동작하는지 빠르게 확인하는 데 쓰인다. 테스트에 포함되지 않은 범위는 확인할 수 없으므로 통과했다는 이유만으로 전체 동작이 올바르다고 판단해서는 안 된다.

이 절의 근거 S38

에이전트의 변경을 풀 리퀘스트로 검토하기

에이전트가 작성한 수정안도 풀 리퀘스트로 검토한다. 변경 내용, 검사 결과, 검토 의견을 함께 확인할 수 있다. 초안 상태에서는 병합할 수 없고 코드 소유자에게 자동 검토 요청도 보내지 않는다. 검토받을 준비가 되면 초안 상태를 해제하고 소유자의 검토를 요청한다.

보호 브랜치를 설정하면 검토 조건을 충족한 변경만 병합할 수 있다. 필요한 승인 수와 코드 소유자 검토, 기존 승인 무효화, 상태 검사, 대화 해결 등을 설정할 수 있다. 에이전트가 낸 제안이라고 조건이 가벼워지지 않는다. 오히려 낸 주체가 사람이 아니므로, 승인 수와 소유자 검토를 그대로 두는 편이 안전하다. 이 판단은 이 글의 편집자 관점이다.

이 절의 근거 S32 · S33

머지 큐의 자동 병합과 재시도 정책

머지 큐를 사용하면 검사가 끝난 변경을 자동으로 병합할 수 있다. 사람이 풀 리퀘스트를 검토하고 승인한 뒤, 쓰기 권한이 있는 사람이 큐에 넣는다. 큐는 대상 브랜치의 최신 커밋과 앞선 변경을 합쳐 검사하고 필수 검사가 모두 통과하면 병합한다. GitHub Actions로 필수 검사를 구현한 워크플로에는 merge_group 이벤트를 추가해야 하며, 빠뜨리면 검사 결과가 보고되지 않아 큐가 멈춘다. 제삼자 CI는 gh-readonly-queue/로 시작하는 임시 브랜치에 푸시되는 커밋을 처리하도록 설정한다. 이 자동화가 확인하는 범위는 팀이 정의한 검사에 한정된다.

재시도 정책은 팀의 선택이다. 실패한 예약을 곧바로 다시 돌릴지, 아침에 사람이 보고 돌릴지, 몇 번까지 돌릴지는 정해진 답이 없다. 재시도 정책이 없으면 실패한 작업이 그대로 남거나, 무한히 반복되면서 자원을 낭비하고 시크릿에 계속 접근할 수 있다. 재시도의 횟수와 간격, 중단 조건을 미리 적어두는 일이 예약 설계의 일부다.

이 절의 근거 S34

가상 예시: 평일 새벽의 수정 작업

아래는 실제로 실행하지 않은 가상 예시다. 한 팀이 평일 새벽에 작은 수정 작업을 에이전트에 맡긴다고 가정하자. 실행이 몰리지 않는 시각을 cron으로 지정하고, 격리된 환경에서 최소 권한으로 작업한다. 에이전트는 수정안을 작성한 뒤 스모크 테스트를 실행한다. 실패하면 작업을 멈추고 다음 날 확인할 기록을 남긴다. 아래 코드는 전체 워크플로에서 on 아래의 schedule만 발췌한 것으로, 실제 작업을 정의하는 부분은 생략했다.

스모크 테스트를 통과한 수정안만 정식 풀 리퀘스트로 제출한다. 코드 소유자의 승인과 상태 검사를 거친 뒤 쓰기 권한이 있는 사람이 머지 큐에 넣는다. 큐는 필수 검사가 모두 통과하면 자동으로 병합한다. 다음 날에는 예약 시작 여부, 실행이 중단된 지점, 스모크 결과, 검토 상태를 순서대로 확인한다. 이 예시에서 속도나 성능을 측정한 것은 아니다. 실제로 도입한다면 대기 시간, 통과율, 사람이 검토하고 수정한 시간을 측정할 수 있다.

on:
  schedule:
    - cron: "20 4 * * 1-5"

실패 양상과 한계

실패 원인은 단계마다 다르다. 예약은 지연되거나 누락될 수 있고, 실행 환경에서는 권한과 시크릿 관련 사고가 생길 수 있다. 스모크 테스트는 범위 밖의 오류를 놓칠 수 있으며, 풀 리퀘스트는 검토를 기다리거나 큐에서 멈출 수 있다. 원인을 찾으려면 예약 시작 시각, 실행 종료 상태, 스모크 결과, 풀 리퀘스트 상태를 단계별로 기록해야 한다.

스모크 테스트가 통과했다면 선택한 핵심 경로가 기대대로 동작했다는 뜻이다. 테스트 범위 밖에는 아직 확인하지 않은 오류가 있을 수 있다. 예약도 정시 실행을 보장하지 않으며, 자동 병합을 사용해도 사람의 검토와 승인은 필요하다. 에이전트가 만드는 수정안이 팀의 검토 처리량보다 많으면 검토하지 못한 풀 리퀘스트가 쌓인다. 맡길 작업의 범위는 검토 처리량에 맞춰 정해야 한다.

이 절의 근거 S36 · S37 · S38 · S32 · S34

실행 결과와 사람의 검토 시간 측정하기

야간 자동화를 운영할 때는 예약의 정시 시작률, 실행 완료율, 스모크 테스트의 적중률, 풀 리퀘스트의 병합률, 사람이 검토하고 수정한 시간을 측정한다. 정시 시작률은 전체 예약 중 제때 시작한 비율이고, 완료율은 시작한 실행 중 끝까지 완료된 비율이다. 스모크 테스트의 적중률은 스모크 테스트 실패 중 실제 결함이 원인이었던 비율로 정의한다. 병합률은 제출한 풀 리퀘스트 중 병합된 비율이다. 사람이 검토하고 수정한 시간이 줄었는지는 자동화의 효과를 판단하는 기준이다. 이 시간이 줄지 않았다면 야간 작업이 사람의 부담을 실제로 덜어줬는지 다시 살펴야 한다.

보안 사고와 실행 누락도 기록한다. 권한 밖의 접근이 있었는지, 시크릿이 유출되지 않았는지, 누락된 예약이 있었는지를 본다. 문제가 보고되지 않았더라도 탐지하지 못했을 가능성이 있으므로, 먼저 모니터링을 갖춰야 한다.

검토 가능한 범위부터 자동화하기

예약 작업은 지연되거나 누락될 수 있으므로 실행 여부부터 기록해야 한다. 격리된 환경에서 필요한 최소 권한으로 실행하고, 스모크 테스트와 사람의 검토를 거친 뒤 머지 큐의 필수 검사가 통과하면 자동으로 병합한다. 단계별 기록이 있어야 작업이 어디서 멈췄는지 확인할 수 있다.

재시도 횟수와 맡길 작업의 범위는 팀의 운영 조건과 검토 여력에 맞춰 정한다. 에이전트의 기본 구성은 「에이전트와 도구 사용」에서, 작업별 모델 배정과 비용·품질 관리는 「역할별 혼합 모델」에서 이어서 살펴볼 수 있다.