Trigger Action

Deplite/trigger-action@v1는 GitHub Actions에서 Deplite 트리거를 호출하는 공식 액션이에요.
호출은 항상 POST /triggers/{trigger-id}/run 한 번이며, wait 입력에 따라 즉시 반환하거나 잡 완료까지 대기해요.

한 줄 요약


- uses: Deplite/trigger-action@v1
  with:
    api-token: ${{ secrets.DEPLITE_API_TOKEN }}
    trigger-id: 00000000-0000-0000-0000-000000000000
    params: '{"ref":"main"}'
    wait: sync

Inputs

이름	필수	기본값	설명
`api-token`	✅	—	Deplite API 토큰. `Authorization: Bearer`로 전송
`trigger-id`	✅	—	호출할 트리거의 UUID
`workflow-name`		—	agent-scope 트리거의 경우 필수. 실행할 워크플로우 이름
`params`		—	트리거 파라미터 JSON 객체 (문자열 형태로 전달)
`ref`		—	워크플로우에 그대로 전달되는 git ref
`debug`		`false`	`true`면 verbose 실행 (`debug: true`로 페이로드 포함)
`wait`		`async`	`async` 즉시 반환, `sync` 잡 완료까지 대기
`idempotency-key`		자동 생성	`Idempotency-Key` 헤더. 미지정 시 `gha-${GITHUB_RUN_ID}-${GITHUB_JOB}-${GITHUB_RUN_ATTEMPT}`
`base-url`		`https://api.deplite.io/v1`	API 베이스 URL 오버라이드

Outputs

이름	언제 채워지나	설명
`job-id`	항상	디스패치된 잡의 UUID
`status`	항상	잡 상태 문자열
`status-url`	응답에 있을 때	잡 상태 페이지 URL (대시보드 콘솔)
`exit-code`	`wait: sync` 에서만	Agent가 보고한 exit code
`output`	`wait: sync` 에서만	잡 출력 페이로드 (객체면 JSON 문자열로 직렬화)

동작 상세

호출

HTTP: 단 1회 — POST ${base-url}/triggers/${trigger-id}/run
헤더: Authorization: Bearer <api-token>, Idempotency-Key: <key>, Content-Type: application/json
바디: { workflowName?, ref?, debug, params? } (각 입력이 있을 때만 포함)
응답: { jobId, status, idempotent, timedOut, exitCode?, errorMessage?, output? }

응답에서 받은 값을 그대로 step output에 매핑해요.

`wait: async` (기본)

호출 즉시 반환하고 액션 자체는 항상 성공(exit 0)으로 끝나요.
후속 처리는 알림 채널(Slack/Discord)이나 워크플로우 마지막 step의 콜백으로 받는 패턴이에요.

`wait: sync`

서버 측에서 잡 완료까지 대기한 뒤 응답을 돌려줘요(클라이언트 폴링 없음 — long-poll). step 실패 판정은 응답을 받은 뒤 다음 순서로 결정돼요.


if (wait === 'sync') {
  if (data.timedOut) {
    core.setFailed(`Job ${jobId} timed out (server-side sync wait).`)
  } else if (typeof data.exitCode === 'number' && data.exitCode !== 0) {
    core.setFailed(`Job ${jobId} exited with code ${data.exitCode}: ${data.errorMessage ?? ''}`)
  } else if (data.status && !['succeeded', 'success', 'completed'].includes(data.status)) {
    core.setFailed(`Job ${jobId} finished with status '${data.status}': ${data.errorMessage ?? ''}`)
  }
}

요약하면 sync 모드는 다음 셋 중 하나라도 만족하면 step을 실패시켜요.

timedOut === true (트리거의 responseTimeoutMs 초과)
exitCode가 숫자이고 0이 아님
status가 succeeded·success·completed 중 하나가 아님

async 모드는 위 검사 자체를 하지 않아요.

Idempotency-Key 자동 생성

idempotency-key를 명시하지 않으면 다음 환경변수에서 조합돼요.


gha-${GITHUB_RUN_ID}-${GITHUB_JOB}-${GITHUB_RUN_ATTEMPT}

환경변수	의미
`GITHUB_RUN_ID`	워크플로우 실행 ID (동일 PR/푸시 내에서 유지)
`GITHUB_JOB`	job 이름
`GITHUB_RUN_ATTEMPT`	재실행 시 증가

같은 GitHub 실행이 그대로 재시도(replay)되면 동일 키가 그대로 사용되어 서버가 중복 잡 생성을 막아줘요.
“Re-run all jobs”는 GITHUB_RUN_ATTEMPT가 증가하므로 새 잡으로 떨어져요.

직접 키를 잡고 싶다면 명시하세요:


- uses: Deplite/trigger-action@v1
  with:
    api-token: ${{ secrets.DEPLITE_API_TOKEN }}
    trigger-id: ${{ vars.TRIGGER_ID }}
    idempotency-key: release-${{ github.sha }}

에러 처리

presign 단계의 HTTP 4xx/5xx는 본문을 포함한 메시지로 즉시 core.setFailed() → step 실패 (exit 1)
네트워크 오류·JSON 파싱 오류도 마찬가지
액션 자체는 자동 재시도를 하지 않아요.
일시적 5xx 대비가 필요하면 GitHub Actions의 step 단위 continue-on-error + 후속 retry step을 활용해주세요.

Agent-scope 트리거

workflow 스코프 트리거는 trigger-id만으로 충분하지만, 한 Agent가 여러 워크플로우를 호스팅하는 agent 스코프 트리거에서는 어떤 워크플로우를 실행할지 명시해야 해요.


- uses: Deplite/trigger-action@v1
  with:
    api-token: ${{ secrets.DEPLITE_API_TOKEN }}
    trigger-id: ${{ vars.DEPLITE_AGENT_TRIGGER_ID }}
    workflow-name: deploy-staging
    params: '{"ref":"main"}'

트리거 스코프 개념은 트리거에서 다뤄요.

응답 객체 형태

wait: sync 응답을 step output으로 받을 때 output 필드는 객체면 JSON 문자열로 직렬화돼서 들어와요.
후속 step에서 다시 파싱해서 쓰세요.


- id: deploy
  uses: Deplite/trigger-action@v1
  with:
    api-token: ${{ secrets.DEPLITE_API_TOKEN }}
    trigger-id: ${{ vars.TRIGGER_ID }}
    wait: sync
 
- name: Read output
  run: |
    echo '${{ steps.deploy.outputs.output }}' | jq '.url'