오토파일럿
시간 또는 Webhook에 따라 반복 작업을 에이전트에게 자동으로 맡깁니다.
오토파일럿는 매일 진행 상황을 요약하거나, 의존성을 정기적으로 확인하거나, 외부 시스템에서 이벤트를 받으면 에이전트를 시작하는 반복 작업에 사용합니다.
각 오토파일럿에는 런북 하나, 실행 주체 하나, 하나 이상의 트리거가 저장됩니다. 트리거되면 Multica가 태스크를 만들거나 에이전트를 바로 실행하고 모든 실행 기록을 보관합니다.
오토파일럿 만들기
사이드바에서 오토파일럿를 열고 템플릿을 선택하거나 빈 상태에서 시작한 뒤 다음 항목을 설정합니다.
- 이름: 오토파일럿가 담당하는 일을 설명합니다.
- 런북: 에이전트가 실행할 때마다 읽는 목표, 배경, 제약, 단계입니다.
- 실행 주체: 에이전트 또는 스쿼드 하나입니다.
- 연결 프로젝트: 선택 항목이며 자동 생성된 태스크를 지정한 프로젝트에 넣습니다.
- 출력 모드: 태스크를 만들거나 실행만 합니다.
- 구독자: 자동 생성된 태스크의 알림을 받아야 하는 멤버입니다.
- 트리거 방식: 일정 또는 Webhook입니다.
저장하면 오토파일럿가 기본적으로 활성화됩니다. 지금 실행으로 언제든 전체 과정을 한 번 수동 실행할 수 있습니다.
출력 모드 선택
| 모드 | 동작 | 적합한 경우 |
|---|---|---|
| 태스크 만들기 | 트리거할 때마다 태스크를 먼저 만든 뒤 실행 주체에 할당합니다. 논의, 상태, 실행 기록이 모두 태스크에 남습니다. | 팀이 확인하거나 승인하거나 후속 처리해야 하는 작업 |
| 실행만 | 태스크 없이 작업을 바로 만듭니다. 결과는 오토파일럿 실행 기록에서만 확인합니다. | 협업 기록이 필요 없는 백그라운드 작업 |
태스크 만들기 모드는 일반 태스크와 같은 작업 큐를 사용합니다. 런타임이 오프라인이어도 태스크를 먼저 만들고 작업은 런타임이 온라인이 될 때까지 기다릴 수 있습니다.
실행만 모드는 트리거하는 시점에 런타임을 사용할 수 있어야 합니다. 사용할 수 없으면 이번 실행이 "건너뜀"으로 표시되며 대기 중인 태스크를 남기지 않습니다.
일정에 따라 실행
일정 편집기에서 실행 시간, 반복 요일, 시간 범위, 시간대를 선택하고 다음 실행 시간을 미리 볼 수 있습니다. 오토파일럿 하나에 여러 일정을 추가할 수 있습니다. 특정 트리거를 개별적으로 켜거나 끄려면 CLI의 autopilot trigger-update를 사용하세요. 인수는 CLI 명령을 참고하세요.
더 복잡한 규칙이 필요하면 표준 5필드 cron을 직접 수정할 수 있습니다.
분 시 일 월 요일예시:
| Cron | 시간대 | 의미 |
|---|---|---|
0 9 * * 1-5 | Asia/Shanghai | 평일 9:00 |
*/30 * * * * | UTC | 30분마다 |
0 3 * * * | UTC | 매일 3:00 |
Cron에는 초가 없으며 시간대에는 Asia/Shanghai 같은 IANA 이름을 사용합니다. 저장하기 전에 페이지의 "다음 실행" 시간을 확인하세요.
Webhook으로 실행
Webhook 트리거를 추가하면 Multica가 고유 URL을 생성합니다. 이 URL에 JSON 객체나 배열을 보내 오토파일럿를 트리거할 수 있습니다.
curl -X POST "$MULTICA_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-001" \
-d '{"event":"build.completed","eventPayload":{"status":"success"}}'Payload는 전달 및 실행 기록에 저장되고 에이전트에게 제공됩니다. 태스크 만들기 모드에서는 이벤트 내용도 태스크 설명에 첨부됩니다.
Webhook 요청에는 다음 제약이 있습니다.
- Body는 유효한 JSON 객체 또는 배열이어야 하며 최대 256 KiB입니다.
Idempotency-Key를 사용하면 발신자가 재시도할 때 중복 실행을 피할 수 있습니다. GitHub에서는X-GitHub-Delivery도 중복 제거에 사용됩니다.- 안정적인 멱등성 key가 없으면 Multica는 중복 요청이 한 번만 실행된다고 보장할 수 없습니다.
- 트리거가 비활성화되었거나 이벤트가 일치하지 않으면 전달이 "무시됨"으로 기록되고 실행은 생성되지 않습니다.
이벤트 필터링
같은 소스에서 여러 종류의 이벤트를 보낸다면 트리거에 이벤트 필터를 추가할 수 있습니다. 각 줄에는 이벤트 이름과 선택적인 action 목록을 입력합니다. 어느 한 줄이라도 일치하면 실행되며 모두 비워 두면 모든 이벤트를 받습니다.
예를 들어 이벤트 이름에 workflow_run, Actions에 completed, failed를 입력하면 이 두 종류의 workflow_run 결과만 받습니다. Multica는 GitHub의 X-GitHub-Event와 body의 action을 포함해 일반적인 요청 header와 payload에서 이벤트와 action을 식별합니다.
Webhook URL 보호
Webhook URL의 token이 호출 자격 증명입니다. 전체 URL을 공개 저장소, 태스크, 스크린샷에 넣지 마세요. URL이 노출되면 URL 옆의 URL 재생성 버튼을 클릭하고 발신자 설정을 즉시 업데이트하세요. 이전 URL은 바로 무효화됩니다.
오토파일럿 생성자, 워크스페이스 owner/admin, 접근 권한을 받은 협업자만 전체 URL을 볼 수 있습니다. 화면에서는 기본적으로 URL의 token을 숨기며 표시하지 않아도 복사할 수 있습니다. URL 또는 눈 아이콘을 클릭하면 전체 주소가 표시됩니다.
Webhook 응답 빠른 참조
발신자를 디버깅할 때 다음 표로 Multica 응답을 확인하세요.
| HTTP 상태 | 응답 상태 | 의미 |
|---|---|---|
| 200 | accepted | 요청을 받아 실행을 만들었으며 전달 ID와 실행 ID를 반환합니다. |
| 200 | skipped | 요청을 받았지만 이번 실행을 건너뛰었습니다. 예를 들어 실행만 모드에서 런타임이 오프라인일 때이며 이유가 포함됩니다. |
| 200 | ignored | 실행을 만들지 않았습니다. 트리거가 비활성화되었거나 오토파일럿가 일시 중지 또는 보관되었거나 이벤트가 필터링되었습니다. reason 필드에 이유가 있습니다. |
| 200 | duplicate | 멱등성 key가 기존 전달과 일치합니다. 원래 전달 ID를 반환하고 다시 실행하지 않습니다. |
| 400 | 오류 메시지 | Body가 비어 있거나 유효한 JSON이 아니거나 JSON 객체/배열이 아닙니다. |
| 401 | rejected | 트리거에 서명 key가 설정되어 있지만 요청에 서명이 없거나 일치하지 않습니다. |
| 404 | 오류 메시지 | URL의 token이 유효하지 않거나 재생성되었습니다. |
| 413 | 오류 메시지 | Body가 256 KiB를 초과합니다. |
| 429 | 오류 메시지 | 요청이 너무 많습니다. 응답 header의 Retry-After 뒤에 다시 시도하세요. |
| 500 | 오류 메시지 | Multica 내부 오류입니다. 발신자는 나중에 다시 시도할 수 있습니다. |
일시 중지, 보관, 이벤트 필터링처럼 비즈니스 규칙에 따른 무시는 4xx가 아니라 200을 반환해 발신자의 반복 재시도를 방지합니다.
이벤트와 action의 추론 순서는 다음과 같습니다.
- body에 문자열
event필드가 있으면 바로 사용합니다. - 없으면
X-GitHub-Event요청 header를 확인하고 body의action과 합쳐github.<event>.<action>으로 만듭니다. - 다음으로
X-Gitlab-Event요청 header를 확인합니다. - 다음으로
X-Event-Type요청 header를 확인합니다. - 다음으로 body의
event,type,action필드를 확인합니다. - 모두 없으면
webhook.received로 기록합니다.
실행 및 전달 기록 확인
실행 기록에는 트리거 출처, 시간, 상태, 연결된 태스크 또는 작업, 실패하거나 건너뛴 이유가 표시됩니다. Webhook 트리거에는 별도 전달 기록도 저장되며 여기에는 해석한 이벤트, 응답, 중복 제거 정보, 실패 이유가 포함됩니다.
처리가 끝난 Webhook 전달은 상세 화면에서 재생할 수 있습니다. 재생은 원래 기록을 바꾸지 않고 새 전달과 실행을 만듭니다. 서명 검증에 실패했거나 아직 큐에서 대기 중인 전달은 재생할 수 없으며 재생에는 중복 제거를 적용하지 않습니다.
실패, 일시 중지, 삭제
실행만 모드의 작업이 실패해도 자동으로 재시도하지 않습니다. 다음 일정은 원래 계획대로 트리거됩니다. 태스크 만들기 모드에서 생성된 작업은 일반 태스크 작업이며 인프라 장애는 작업의 규칙에 따라 처리됩니다.
Multica는 최근 실행이 계속 실패하는지 정기적으로 확인합니다. 지난 7일 동안 완료되거나 실패한 실행이 50회 이상이고 실패율이 90% 이상이면 시스템이 오토파일럿를 일시 중지하고 생성자에게 알립니다. 원인을 해결한 뒤 수동으로 다시 시작할 수 있습니다.
수동으로 일시 중지하면 일정, Webhook, "지금 실행"이 모두 중지됩니다. 삭제는 실제로 보관 처리합니다. 이후 트리거는 중지하지만 실행 및 전달 기록은 유지합니다.
관리 권한
- 모든 워크스페이스 멤버가 오토파일럿를 만들 수 있습니다.
- 생성자와 워크스페이스 owner/admin은 수정, 실행, 삭제, 트리거 관리를 할 수 있습니다.
- 생성자와 owner/admin은 협업자를 "관리 접근"에 추가할 수 있습니다.
- 협업자는 수정, 실행, 트리거 관리를 할 수 있지만 다른 사람에게 권한을 다시 부여할 수는 없습니다.
- 오토파일럿를 관리할 수 있다고 해서 반드시 그 오토파일럿가 사용하는 에이전트를 실행할 수 있는 것은 아닙니다. 에이전트 Access는 계속 적용됩니다.
CLI 사용
multica autopilot get <autopilot-id> --output json
multica autopilot trigger <autopilot-id>
multica autopilot runs <autopilot-id>
multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>autopilot get은 기본적으로 webhook_token, webhook_path, webhook_url을 null로 설정하고 대신 has_webhook_token과 webhook_token_hint를 반환합니다. 실제 자격 증명이 꼭 필요할 때만 --show-secrets를 추가하세요. CLI는 경고를 stderr로 출력하므로 파이프로 전달되는 JSON은 유효하게 유지됩니다.
전체 인수는 CLI 사용을 참고하세요.
다음 단계
- 태스크를 에이전트에게 할당하기 — 할당과 확인 창을 알아봅니다.
- 인박스와 구독 — 실행 알림이 도착하는 위치를 확인합니다.
- 작업 — 실행 상태와 실패 처리를 알아봅니다.