Skip to Content
문서워크플로우 호출

워크플로우 호출

Agent와 워크플로우 이름을 경로에 넣어 호출하고 실행 입력은 params로 전달해요.
실행 내용은 Agent에 있는 YAML 파일에서 정해요.

엔드포인트와 인증

POST/v1/run/{agentName}/{workflowName}권한 agent · workflow

Base URL은 https://api.deplite.io이고 실행 요청은 201 Created로 접수돼요.
API Token은 dpl_ 뒤에 64자리 16진수가 오는 형식이에요.
조직 owner가 콘솔에서 발급하며 평문은 발급 시 한 번만 표시돼요.
지정한 Agent에서 호출 가능한 워크플로우를 실행하려면 agent 권한 토큰을, 특정 워크플로우만 실행하려면 해당 Agent와 워크플로우에 묶인 workflow 권한 토큰을 사용해주세요.
조직 전체 실행 권한을 가진 토큰은 없어요.

경로 파라미터

agentNamestring필수

대상 Agent 이름이에요.
URL 인코딩 후 대소문자까지 정확히 입력해주세요.

1 ~ 128자
workflowNamestring필수

대상 워크플로우 이름이에요.
URL 인코딩해주세요.

1 ~ 128자

헤더

Idempotency-Keystring

같은 실행 요청의 재시도에서 기존 Job을 반환하도록 하는 선택 헤더예요.

요청 본문

refstring

호출할 ref예요.
YAML과 콘솔의 허용 범위에 따라 검증해요.

1 ~ 255자
paramsobject

워크플로우 입력값이에요.
선언한 schema로 검증해요.

approvalobject

워크플로우에서 실행 승인을 선언한 경우 필요한 승인 값이에요.

waitboolean

true면 결과를 기다려요.
생략하면 Job을 접수하고 바로 응답해요.

waitTimeoutMsinteger

wait: true일 때 기다릴 시간이에요.

1000 ~ 300000ms, 기본값 30000ms
metaobject

호출 출처 기록용 메타데이터예요.

repostring

저장소 이름이에요.

최대 255자
run_urlstring · URL

호출한 CI 실행의 HTTP 또는 HTTPS 주소예요.

최대 2048자
shastring

호출한 소스 commit SHA예요.

최대 128자

응답

성공하면 HTTP 201과 아래 필드를 돌려줘요.

jobIdstring · uuid

접수한 Job ID예요.

statusstring

접수 시점의 Job 상태예요.

허용 값queuedrunningsuccessfailedtimeoutrejectedcanceled
consoleUrlstring · URL

Job 결과를 확인할 콘솔 주소예요.

idempotentboolean

멱등 재호출에서 기존 Job을 반환했는지 나타내며 해당 경우에 포함돼요.

요청 본문

요청 본문에는 선택 항목과 조건부 필수 항목이 있어요.
ApiOperation의 요청 본문 필드를 확인해주세요.

{ "ref": "main", "params": { "environment": "production" }, "wait": true, "waitTimeoutMs": 30000, "meta": { "repo": "acme/service", "run_url": "https://github.com/acme/service/actions/runs/123", "sha": "a1b2c3d4" } }

알 수 없는 본문 키는 무시돼요.
debug: true는 허용되지 않고 400 invalid_request 응답을 받아요.

중복 요청 방지

선택 헤더 Idempotency-Key에 호출마다 고유한 값을 넣을 수 있어요.
같은 Agent, 워크플로우, 키로 다시 호출하면 기존 Job을 반환하고 응답에 "idempotent": true가 포함돼요.
같은 키에 다른 요청 본문을 보내면 409 idempotency_conflict를 반환해요.

대기와 응답

기본 호출은 Job을 큐에 넣고 결과를 기다리지 않아요.
wait: true면 결과가 준비될 때까지 기다리며 기본 대기 시간은 30초예요.
waitTimeoutMs는 1000~300000ms 범위에서 지정할 수 있어요.

Agent가 오프라인일 때 wait: true로 호출하면 큐에 넣지 않고 즉시 status: "rejected", reason: "agent_offline"으로 응답해요.
wait 없이 호출해도 Agent가 오프라인이면 status가 rejected로 와요.
대기 시간 안에 완료되지 않으면 timedOut: true가 오고 Job은 계속 실행될 수 있어요.
이 경우 status는 queued 또는 running일 수 있어요.
비동기·동기·timeout·rejected 응답은 모두 HTTP 201 Created예요.

비동기 호출은 Job ID, 상태, 콘솔 URL을 반환해요.

{ "jobId": "550e8400-e29b-41d4-a716-446655440000", "status": "queued", "consoleUrl": "https://..." }

wait: true 호출은 다음 필드를 포함한 결과 응답을 반환해요.

{ "jobId": "550e8400-e29b-41d4-a716-446655440000", "status": "success", "exitCode": 0, "errorMessage": null, "output": { "deployedRef": "main" }, "reason": null, "consoleUrl": "https://...", "timedOut": false, "idempotent": false }

output에는 YAML에 선언한 outputs 값이 담겨요.
Job 상태는 queued, running, success, failed, timeout, rejected, canceled 중 하나예요.
queued와 running은 진행 중이고 나머지는 종료 상태예요.
비동기 호출 결과는 응답의 consoleUrl에서 확인해주세요.
호출 결과가 필요한 자동화에서는 wait: true를 사용해주세요.

호출 허용 선언

외부 호출은 Agent에 둔 워크플로우 YAML의 on.webhook 선언으로 열어요.
on: 선언이 없으면 호출할 수 없고 403 not_callable 응답을 받아요.

name: deploy on: webhook: refs: [main, "release/*"] steps: - run: ./deploy.sh

webhook: 아래에 refs가 없거나 빈 목록이면 모든 ref를 허용해요.
refs를 지정하면 최대 50개까지 둘 수 있고 각 항목은 1~255자예요.
*만 와일드카드이며 /를 넘어 매칭해요.
대소문자를 구분하고 *가 없는 패턴은 정확히 일치해야 해요.
허용 선언의 전체 규칙은 워크플로우 YAML 스펙에서 확인해주세요.

콘솔에서는 호출을 새로 열 수 없고 호출을 잠그거나 허용 ref를 좁히는 것만 가능해요.
실제 허용 ref는 YAML에 선언한 ref와 콘솔에서 좁힌 ref의 교집합이에요.
콘솔의 워크플로우 화면에서 지금 실행을 선택하면 ref, params, 대기 여부를 지정해 바로 호출할 수 있어요.

실행 승인

YAML에서 승인 방식을 선언하는 방법은 워크플로우 YAML의 실행 승인을 참고해주세요.
선언된 워크플로우를 호출할 때는 요청 body에 approval 객체를 포함해야 해요.
서버는 객체의 모양과 크기만 검사하고 승인 진위는 Agent 노드가 판정해요.

지원하는 body 형식은 다음과 같아요.
각 형식에 적힌 필드는 모두 필요하고 그 밖의 키가 있으면 요청을 거절해요.

TOTP:

{ "method": "totp", "code": "123456" }

HMAC:

{ "method": "hmac", "keyId": "ci-1", "nonce": "…", "ts": 1792000000, "sig": "…" }

Ed25519 서명:

{ "method": "signature", "alg": "ed25519", "keyId": "op-1", "nonce": "…", "ts": 1792000000, "sig": "…" }

인증서 체인을 사용하는 ECDSA P-256 서명:

{ "method": "signature", "alg": "ecdsa-p256-sha256", "certChain": ["MII…"], "nonce": "…", "ts": 1792000000, "sig": "…" }
필드형식과 제한
code숫자 6자리 문자열
keyId1~128자
nonce난수 16~64바이트를 padding 없이 base64url로 인코딩한 값이에요. 같은 nonce는 재사용할 수 없어요.
ts호출 시각의 Unix 초를 나타내는 정수예요.
sigpadding 없는 base64url이에요. HMAC은 디코딩 결과 32바이트, 서명은 64바이트예요.
alged25519 또는 ecdsa-p256-sha256이에요.
certChain표준 Base64 DER 인증서 배열이에요. leaf 인증서가 첫 항목이며 1~3개, 합계 16KB 이하여야 해요.

signature 방식은 keyId와 certChain 중 하나만 사용해야 해요.
서명은 다음 정규 요청을 UTF-8로 인코딩해 만들고 JSON 키는 사전순으로 정렬하며 공백을 넣지 않아요.

{"agentId":"<uuid>","nonce":"<base64url>","params":{},"ref":null,"ts":1792000000,"v":1,"workflow":"<name>"}

agentId는 대상 Agent ID예요.
params는 요청 body의 params 그대로이며 생략하면 {}예요.
ref는 요청 ref이며 없거나 빈 문자열이면 null이에요.
nonce와 ts는 approval 값과 같고 v는 1, workflow는 워크플로우 이름이에요.
HMAC은 sig = base64url(HMAC-SHA256(key, 정규 요청))으로 계산해요.
Ed25519는 64바이트 서명을 사용해요.
ECDSA P-256 SHA-256은 DER이 아닌 64바이트 r‖s IEEE P1363 서명을 사용해요.

서명 대상 params에는 숫자 안전 정수만 사용할 수 있어요.
소수는 string param으로 전달해주세요.
중첩 객체를 포함해 모든 객체 키는 ASCII여야 하고 파일 참조는 사용할 수 없어요.
문자열 값 자체에는 제한이 없어요.

승인 방식과 파라미터 스키마 조회

GET/v1/run/{agentName}/{workflowName}권한 workflow 실행 권한

실행과 같은 토큰으로 조회하면 대상 ID, 호출 허용 정보와 params schema를 받아요.
callable.approval은 { "methods": [...] } 또는 null이에요.
호출 허용 선언이 없으면 403 not_callable을 반환해요.
서버 로그에는 승인 방식과 keyId 또는 인증서 subject만 남아요.

경로 파라미터

agentNamestring필수

대상 Agent 이름이에요.
1 ~ 128자이며 URL 인코딩해주세요.

workflowNamestring필수

대상 워크플로우 이름이에요.
1 ~ 128자이며 URL 인코딩해주세요.

응답

성공하면 HTTP 200과 아래 필드를 돌려줘요.

오류

401
token_missing
토큰이 없어요.
401
token_invalid
토큰이 무효·폐기·만료됐어요.
403
token_not_authorized
토큰 권한 범위 밖이에요.
403
not_callable
호출 허용 선언이 없어요.
404
agent_not_found
Agent를 찾을 수 없어요.
404
workflow_not_found
워크플로우를 찾을 수 없어요.
409
agent_name_ambiguous
조직 안에서 Agent 이름이 중복돼요.
409
workflow_invalid
Agent가 무효로 보고한 워크플로우예요.
본문 reason에 사유, invalidCode에 무효 종류가 담겨요.

공통 오류는 에러 코드에서 확인해주세요.

승인 판정은 서버가 작업을 보낸 뒤 Agent에서 비동기로 이뤄져요.
wait: true로 호출하고 대기 시간 안에 작업이 끝나면 최종 status: "rejected"와 reason이 응답에 담겨요.
대기 시간이 끝나면 timedOut: true가 오고 status는 queued 또는 running일 수 있어요.
wait 없이 호출하면 접수 상태만 반환되므로 결과는 consoleUrl의 콘솔 작업 화면에서 확인해주세요.

reason의미
approval_required승인이 없어요.
approval_method_not_allowed선언되지 않은 승인 방식이에요.
approval_invalid코드·서명·키 검증 실패, HMAC·서명 방식의 params 정규화 실패(소수, 안전 정수 범위 밖 숫자, 비 ASCII 객체 키), 또는 TOTP 실패 횟수 제한이에요.
approval_expired서명 시각이 허용된 ±300초 범위를 벗어났어요.
approval_replayedTOTP 스텝 또는 nonce를 재사용했어요.
approval_untrusted_cert인증서 체인 또는 allowed-subjects 검증에 실패했어요.
approval_agent_mismatch예약 코드예요. 현재는 approval_invalid로 거부돼요.

params schema 위반은 승인 확인 전에 걸러져 Job이 failed(param validation: ...)로 끝나요.

오류 코드

오류 응답은 HTTP 상태와 함께 statusCode, message, error, code를 포함해요.

{ "statusCode": 400, "message": "Invalid request", "error": "Bad Request", "code": "invalid_request" }
400
invalid_request

입력 검증 실패, 요청 형식 오류 또는 debug 사용이에요.

ref_required

ref 제한이 있지만 요청에 ref가 없어요.

ref_not_allowed

YAML에서 허용하지 않은 ref예요.

ref_blocked

콘솔에서 좁힌 ref 범위에 들지 않아요.

invalid_params

호출 시점에 검증한 params가 선언된 schema와 달라요.

invalid_approval

approval 모양 또는 크기가 잘못됐어요.

approval_required

선언된 승인이 요청에 없어요.

approval_method_not_allowed

선언되지 않은 승인 방식이에요.

401
token_missing

토큰이 없어요.

token_invalid

토큰이 무효·폐기·만료됐어요.

403
token_not_authorized

토큰 권한 범위 밖이에요.

not_callable

워크플로우에 호출 허용 선언이 없어요.

workflow_locked

콘솔에서 워크플로우 호출이 잠겼어요.

agent_suspended

Agent가 정지됐어요.

404
agent_not_found

Agent를 찾을 수 없어요.

workflow_not_found

워크플로우를 찾을 수 없어요.

409
agent_name_ambiguous

조직 안에서 Agent 이름이 중복돼요.

workflow_invalid

Agent가 무효로 보고한 워크플로우예요.
본문 reason에 사유, invalidCode에 무효 종류가 담겨요.

idempotency_conflict

같은 Idempotency-Key에 다른 요청 본문을 보냈어요.

429
rate_limited

워크플로우 또는 토큰 호출 한도를 초과했어요.

params를 선언하지 않은 워크플로우에 params를 보내거나 approval을 선언한 워크플로우를 호출하는 경우에는 Agent가 실행 전에 params를 검사해요.
approval workflow에서는 승인 확인 전에 검사하고 schema 위반이면 Job이 failed로 끝나며 errorMessage에 param validation: ...이 담겨요.
429 rate_limited 본문에는 scope(workflow 또는 token), window(minute, hour, day), limit, observed가 포함돼요.
이 응답에는 Retry-After 헤더가 없어요.

409 workflow_invalid는 Agent가 무효로 보고한 워크플로우를 조회하거나 호출했을 때 반환돼요.
Agent에 같은 name을 가진 워크플로우 파일이 둘 이상 있으면 무효가 돼요.
본문의 reason에는 Agent가 보고한 사유가, invalidCode에는 무효 종류(duplicate_name)가 담겨요.
Agent에서 파일을 하나만 남기면 다시 호출할 수 있어요.
자세한 내용은 워크플로우 관리를 참고해주세요.

{ "statusCode": 409, "message": "Workflow \"hello\" is invalid: workflow \"hello\": name is defined in 2 files (hello.yml, team/hello.yml)", "error": "Conflict", "reason": "workflow \"hello\": name is defined in 2 files (hello.yml, team/hello.yml)", "invalidCode": "duplicate_name", "code": "workflow_invalid" }

레이트 리밋

워크플로우별 한도와 토큰별 한도가 각각 적용돼요.
워크플로우와 토큰에 다음 공통 상한보다 낮은 한도를 설정할 수 있어요.

범위분당 한도시간당 상한일간 상한
상한(워크플로우·토큰 공통)120360050000

토큰의 분당 기본 한도는 Free 플랜에서 60회, Pro 플랜에서 600회예요.

플랜기기 수워크플로우 수
Free25
Pro1050

curl 예시

위 요청 코드 패널은 Idempotency-Key를 포함한 비동기 호출 예시예요.
wait: true를 지정하면 결과를 기다려요.

curl --fail-with-body -sS -X POST \\ "https://api.deplite.io/v1/run/prod-agent/deploy" \\ -H "Authorization: Bearer dpl_..." \\ -H "Content-Type: application/json" \\ -d '{"ref":"main","wait":true,"waitTimeoutMs":30000,"params":{"environment":"production"}}'

동기 실행 응답 예시는 다음과 같아요.

{ "jobId": "job-id", "status": "success", "exitCode": 0, "errorMessage": null, "output": { "deployedRef": "main" }, "reason": null, "consoleUrl": "https://deplite.io/...", "timedOut": false, "idempotent": false }

관련 문서

최종 수정 일자: