워크플로우
이 문서는 워크플로우 YAML의 모든 필드를 다뤄요.
입문자라면 워크플로우 생성부터 보시는 게 좋아요.
파일 규칙
- 위치: Agent 데이터 디렉토리 아래
workflows(기본<data-dir>/workflows;--workflows-dir또는DEPLITE_WORKFLOWS_DIR로 재정의하며, 플래그가 우선해요) - 확장자:
.yaml또는.yml - 파일이 추가·수정·삭제되면 Agent가 파일시스템 이벤트로 즉시 감지해서 반영해요
한 파일에는 워크플로우 하나를 담아주세요.
워크플로우 이름은 파일명이 아니라 YAML의 name 값으로 구분하므로, 파일명과 달라도 괜찮아요.
root 사용자로 설치하면 기본 워크플로우 경로는 /root/.config/deplite-agent/workflows예요.
데이터 디렉토리 기본 경로 등 Agent 호스트 설정은 Agent 운영을 참고해주세요.
실제 워크플로우 경로는 deplite-agent status에서 확인해주세요.
잘못된 YAML 파일은 해당 파일만 건너뛰고 다른 워크플로우는 계속 반영돼요.
콘솔에서 워크플로우가 보이지 않으면 Agent 로그의 workflow load failed 항목을 확인해주세요.
최상위 필드
| 필드 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
name | string | ✓ | — | 워크플로우 식별자. Agent 안에서 유일하며 1~128자 |
description | string | — | 설명. 콘솔과 GET /v1/workflows 응답에 표시돼요 | |
version | string | — | 자유 형식 버전 표기. semver를 강제하지 않으며 콘솔과 GET /v1/workflows에 표시돼요 | |
schema-version | int | 1 | YAML 포맷 버전. 현재 1만 지원해요 (검증 규칙 참고) | |
steps | object[] | ✓ | — | 최소 1개 |
on | object | — | 이 워크플로우를 이름으로 직접 호출할 수 있는지 선언 (호출 허용 선언 참고) | |
timeout-minutes | int | (제한 없음) | 워크플로우 전체 실행을 감싸는 제한. step별 timeout과는 별개이고, 미지정 시 Agent 측 제한은 없어요. 다만 플랫폼이 실행을 최대 1시간으로 제한해요 | |
env | object | {} | 모든 step에 적용되는 환경변수 | |
secrets | (string | object)[] | [] | Agent 프로세스의 DEPLITE_SECRET_<KEY> 환경변수에서 가져와 마스킹할 시크릿 목록 (시크릿 참고) | |
outputs | object[] | [] | step이 캡처한 값을 워크플로우 결과로 노출 (출력 참고) | |
params | object[] | [] | 호출 시 받을 값을 선언해요 (입력 파라미터 참고) | |
retry | object | — | 모든 step에 적용할 공통 재시도 규칙 (재시도 참고) | |
limits | object[] | [] | Agent 기기에서 적용할 실행 빈도 제한 (실행 빈도 제한 참고) | |
force-allowed | bool | true | 강제 실행 요청이 limits를 건너뛰도록 허용할지 정해요 (실행 빈도 제한 참고) | |
log-retention | int | 50 | DEPLITE_LOG_DIR이 설정된 경우 작업이 끝날 때 로그 디렉토리 전체에서 최근 수정된 N개만 남겨요 (로그 보존 참고) |
호출 허용 선언
워크플로우를 이름으로 직접 호출하려면 yaml에 on: 블록으로 호출 허용을 선언해야 해요.
호출 허용 여부는 콘솔이 아니라 Agent에 놓인 워크플로우 파일에서 선언해요.
콘솔은 이미 열린 범위를 더 좁히거나 잠그는 방향으로만 관여해요.
name: deploy
on:
webhook:
refs: [main, 'release/*']
steps:
- name: Deploy
run: ./deploy.sh표기별 의미
| 표기 | 의미 |
|---|---|
on: 키 자체가 없음 | 호출 허용 미선언. 외부 호출은 not_callable로 거절돼요 |
on: 단독 또는 on: {} | 호출 허용 미선언. 외부 호출은 not_callable로 거절돼요 |
on: → webhook: (아래가 비어 있음) | 호출 가능. 모든 ref 허용 |
on: → webhook: → refs: [] | 호출 가능. 모든 ref 허용 (webhook: 아래를 비운 것과 같아요) |
on: → webhook: → refs: [...] | 호출 가능. 목록에 매칭되는 ref만 허용 |
webhook: 아래를 비워 두면 모든 ref를 허용해요.
특정 브랜치만 열고 싶다면 refs에 glob 목록을 적어 주세요.
refs glob 규칙
| 패턴 | 매칭 |
|---|---|
main | 대소문자를 구분해 main만 정확히 일치해요 |
release/* | release/1.2, release/1.2/rc 모두 매칭해요. *는 /를 넘어 매칭해요 |
?, [] | 와일드카드가 아니라 리터럴 문자로 취급돼요 |
refs는 최대 50개까지 지정할 수 있고, 각 값은 1~255자예요.
와일드카드는 *만 지원해요.
**도 *와 같은 방식으로 동작해요.
ref 값에서 refs/heads/ 같은 접두사는 자동으로 제거하지 않아요.
기존 트리거로 실행하던 워크플로우는 on 선언과 관계없이 종전대로 동작해요.
*는 /도 매칭해요.
release/*로 적으면 release/1.2/rc 같은 하위 경로까지 함께 열려요.
한 단계만 열고 싶다면 ref 이름 규칙 자체를 좁히는 편이 안전해요.
알 수 없는 키의 처리
on: 아래에서 webhook: 외의 키는 무시돼요.
이름 기반 호출 허용 선언은 on.webhook에서만 처리돼요.
on.webhook에서 허용되는 키는 refs와 approval뿐이에요.
이 블록 아래의 오타나 알 수 없는 키는 워크플로우 파일 전체를 로드 실패로 만들어요.
이때 해당 워크플로우는 스캔 결과에서 빠지고, 콘솔 목록에서도 사라져요.
콘솔에서 워크플로우가 갑자기 보이지 않는다면 파일이 지워졌거나 yaml에 오류가 있는 경우예요.
approval 하위 블록도 같은 방식으로 엄격하게 검증돼요.
유효 범위
실제로 허용되는 ref는 yaml에 선언한 범위와 콘솔에서 건 제한의 교집합이에요.
yaml에서 열지 않은 ref는 콘솔로 열 수 없고, yaml에서 열어 둔 ref는 콘솔에서 즉시 좁히거나 잠글 수 있어요.
실행 승인
on.webhook.approval을 선언하면 Deplite를 거쳐 들어오는 /v1/run과 콘솔의 지금 실행 요청마다 Agent가 노드 로컬 자료로 승인을 확인해요.
검증에 통과해야 첫 step을 실행해요.
기본값은 승인 미사용이며, 서버는 approval 객체의 모양과 허용 방식만 확인하고 진위는 Agent가 판정해요.
호출 body의 형식, 서명 생성과 거부 코드는 워크플로우 호출의 실행 승인을 참고해주세요.
on:
webhook:
refs: [main]
approval:
totp:
secret-file: /etc/deplite/approval/deploy.totp
hmac:
keys-file: /etc/deplite/approval/hmac-keys.yaml
signature:
trusted-keys-file: /etc/deplite/approval/keys.yaml
trusted-ca-file: /etc/deplite/approval/ca.pem
allowed-subjects: ["ops-*"]approval에는 totp, hmac, signature 중 하나 이상을 선언해주세요.
빈 approval: 값이나 approval: null은 허용되지 않으며, 이 블록과 하위 블록의 알 수 없는 키는 파일 로드 오류예요.
모든 파일 경로는 절대경로여야 해요.
파일이 없거나 형식이 맞지 않으면 워크플로우 로드에 실패해 콘솔 목록에서 사라져요.
파일 변경은 다음 워크플로우 스캔부터 반영돼요.
| 설정 | 타입·조건 | 로컬 파일 형식 |
|---|---|---|
totp.secret-file | TOTP를 선언하면 필수 | 공백과 패딩이 없는 Base32 텍스트. 디코딩 결과가 16바이트 이상이어야 해요 |
hmac.keys-file | HMAC을 선언하면 필수 | keyId: 표준 Base64 키 형태의 YAML 맵. 각 키는 디코딩 결과가 32바이트 이상이어야 해요 |
signature.trusted-keys-file | 선택 | keyId: | 아래 PEM 공개키를 두는 YAML 맵. Ed25519 또는 ECDSA P-256만 지원해요 |
signature.trusted-ca-file | 선택 | PEM 인증서가 하나 이상 있어야 해요 |
signature.allowed-subjects | 선택 | 인증서 체인 서명에서 leaf의 CN·DNS·이메일·URI 이름 중 하나를 검사해요. *만 와일드카드이며 전체 문자열과 대소문자를 구분해요 |
signature에는 trusted-keys-file과 trusted-ca-file 중 하나 이상이 필요해요.
인증서 체인으로 서명할 때는 leaf 인증서의 이름이 allowed-subjects 항목 중 하나와 일치해야 해요.
서명 요청의 인증서 체인은 leaf 인증서부터 최대 3개까지 표준 Base64 DER 문자열로 전달해주세요.
지원하는 서명 알고리즘은 Ed25519 또는 SHA-256을 사용하는 ECDSA P-256이에요.
예를 들어 HMAC 키 파일은 다음처럼 작성해요.
ci-1: <openssl rand -base64 32 출력값>공개키 파일은 key ID 아래에 PEM 블록을 넣어요.
ops-1: |
-----BEGIN PUBLIC KEY-----
<PEM 공개키 내용>
-----END PUBLIC KEY-----키 파일은 Agent 서비스 유닛 사용자 소유의 0600 권한으로 두는 것을 권장해요.
Agent를 root로 실행한다면 root 소유 0600으로 두면 돼요.
서버와 콘솔에는 승인 방식 이름(methods)만 보고되며 파일 경로와 비밀 값은 전달되지 않아요.
승인 설정을 이해하지 못하는 구버전 Agent는 해당 워크플로우를 로드하지 않아요.
TOTP는 RFC 6238, SHA-1, 6자리, 30초 주기를 사용하며 앞뒤 1스텝을 허용해요.
같은 스텝의 코드는 재사용할 수 없고, 워크플로우별 5분 안에 5회 실패하면 잠시 맞는 코드도 거부돼요.
TOTP는 같은 30초 창에서 가로챈 코드를 다른 params와 먼저 사용할 수 있으므로 사람이 확인했다는 2차 확인용으로 사용해주세요.
앱·CI·파괴적 작업에는 HMAC 또는 서명을 권장하고, TOTP 비밀은 워크플로우마다 따로 두세요.
승인 대상 파라미터의 숫자는 안전한 정수만 허용하므로 소수 값은 문자열 파라미터로 전달해주세요.
승인 대상 params 안의 모든 객체 키는 ASCII 문자(0x00~0x7F)로 작성해주세요.
승인 대상 파라미터에는 파일 참조를 사용할 수 없어요.
서명 시각은 현재 시각에서 ±300초, TOTP는 ±30초까지 허용해요.
시계 오차를 줄이기 위해 chrony 또는 systemd-timesyncd로 시계를 동기화하는 것을 권장해요.
키를 교체할 때는 새 keyId를 함께 등록한 뒤 이전 키를 파일에서 삭제해요.
자료를 만드는 명령은 다음과 같아요.
head -c 20 /dev/urandom | base32 > deploy.totp
openssl rand -base64 32
openssl genpkey -algorithm ed25519 -out signer-ed.pem
openssl pkey -in signer-ed.pem -pubout -out signer-ed.pub.pem
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out signer-ec.pem
openssl pkey -in signer-ec.pem -pubout -out signer-ec.pub.pem승인을 선언한 워크플로우는 Agent가 오프라인이면 대기열에 넣지 않고 wait 여부와 관계없이 응답 status가 즉시 rejected예요.
reason: agent_offline은 wait 응답이나 콘솔에서 확인할 수 있어요.
승인 거부 코드
| 거부 코드 | 의미 |
|---|---|
approval_required | 승인이 필요해요 |
approval_method_not_allowed | 워크플로우에서 허용하지 않은 방식이에요 |
approval_invalid | 코드, 서명, 키, 파라미터 또는 재시도 제한 검증에 실패했어요 |
approval_expired | 서명 시각이 허용 범위를 벗어났어요 |
approval_replayed | TOTP 스텝 또는 서명 nonce가 이미 사용됐어요 |
approval_untrusted_cert | 인증서 체인이나 허용된 subject를 검증하지 못했어요 |
approval_agent_mismatch | 예약 코드예요. 현재 승인 형식에서는 approval_invalid로 거부돼요 |
앱 OTA 업데이트(App Deploy)용 워크플로우에는 approval을 선언하지 말아주세요.
승인을 선언하면 승인 없는 작업은 OTA를 포함해 모두 거부돼요.
OTA는 별도의 아티팩트 서명 검증으로 보호돼요 (App Deploy 참고).
입력 파라미터
params는 호출 시 받을 값을 선언하는 object 배열이에요.
각 항목의 name과 type은 필수이고, 같은 이름을 두 번 선언할 수 없어요.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | ✓ | ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ 형식이며 중복될 수 없어요 |
type | string | ✓ | string, number, boolean, enum 중 하나예요 |
required | bool | 값이 없을 때 거절할지 정해요 | |
description | string | 입력값 설명이에요 | |
default | 타입별 값 | 값이 없고 필수값이 아니면 사용할 기본값이에요 | |
pattern | string | string 전용 정규식 제약이에요 | |
options | string[] | enum이면 ✓ | enum에서 허용할 문자열 목록이에요 |
min, max | number | string에서는 길이, number에서는 값 범위예요. 다른 타입에는 사용할 수 없고 min은 max보다 클 수 없어요 | |
mask | bool | 값을 작업 로그에서 가려요. Agent 로컬 정책이라 서버로 전달되지 않아요 |
description은 콘솔에 표시돼요.
required: true와 default는 함께 쓸 수 없어요.
default도 해당 타입과 options, pattern, min, max 제약을 만족해야 해요.
값이 없으면 필수 항목은 거절되고, 기본값이 있으면 기본값을 사용하며, 둘 다 아니면 주입하지 않아요.
params를 하나 이상 선언하고 approval을 선언하지 않은 워크플로우는 서버가 호출 시점에 검사해, 선언하지 않은 키나 제약 위반 값을 HTTP 400 invalid_params로 거절해요.
그 밖의 경우에는 Agent가 실행 전에 검사해요.
params를 선언하지 않은 워크플로우에 params를 보낸 경우와 approval을 선언한 워크플로우가 여기에 해당해요.
Agent 검사에서 위반하면 작업이 failed로 끝나고 errorMessage에 param validation: ...이 담겨요.
승인 워크플로우는 승인 확인보다 params 검사를 먼저 해요.
pattern은 RE2 문법이며 최대 512자예요.
전방탐색 (?=, 후방탐색, 역참조 \1은 지원하지 않아요.
부분 일치로 검사하므로 전체 문자열 일치가 필요하면 ^...$로 감싸야 해요.
pattern 검사 대상 값은 최대 8192자예요.
문자열의 min·max는 ASCII 기준으로 작성하는 것을 권장해요.
서버는 UTF-16 길이, Agent는 바이트 수로 세기 때문에 한글 등 비 ASCII 문자열은 결과가 다를 수 있어요.
number는 서버가 숫자 문자열(예: "42")도 숫자로 받아요.
boolean은 true·false 또는 문자열 "true"·"false"를 받아요.
params:
- name: target
type: enum
required: true
options: [staging, production]
- name: image_tag
type: string
pattern: '^[a-z0-9._-]{1,64}$'
- name: replicas
type: number
default: 2
min: 1
max: 10
- name: api_key
type: string
mask: true각 값은 step에 DEPLITE_PARAM_<대문자 이름>으로 주입되고 -는 _로 바뀌어요.
값은 셸 명령에 직접 보간되지 않아요.
params는 콘솔과 GET /v1/workflows의 paramsSchema로 노출되며 mask는 그 응답에서 제외돼요.
Step 필드
| 필드 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
name | string | ✓ | — | 워크플로우 안에서 고유해야 해요 |
run | string | ✓ | — | 실행할 셸 명령 (multi-line 가능) |
id | string | — | step 식별자. 형식 ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$, 워크플로우 안에서 유일해야 해요. 출력값 캡처와 시크릿 scope 지정에 쓰여요 | |
verbose | bool | false | 디버그 실행일 때 원본 로그를 남길 step인지 표시해요 | |
timeout-minutes | int | 30분 | 이 step 하나의 timeout. 미지정 시 30분 고정이며, 워크플로우 timeout-minutes를 상속하지 않아요 | |
working-directory | string | (Agent 작업 폴더) | cd 후 실행 | |
env | object | {} | step별 환경변수 | |
shell | string | (Agent 기본 셸) | 이 step만 다른 셸로 실행할 때 사용 | |
continue-on-error | bool | false | 실패해도 다음 step 진행 | |
retry | object | — | 이 step에 적용할 재시도 규칙. 최상위 retry보다 우선해요 (재시도 참고) |
step은 적어 둔 순서대로 하나씩 실행돼요.
실패하면 다음 step은 실행하지 않아요.
continue-on-error: true인 step은 실패, 시간 초과, 0이 아닌 종료 코드가 발생해도 다음 step으로 진행해요.
시크릿 값은 stdout/stderr에 노출되어도 ***로 자동 마스킹돼요.
재시도
최상위 retry는 모든 step에 적용돼요.
step에 자체 retry가 있으면 최상위 설정과 합치지 않고 그 step 설정만 사용해요.
| 필드 | 타입 | 필수 | 기본값·제약 |
|---|---|---|---|
max-attempts | int | ✓ | 첫 시도를 포함한 전체 시도 횟수. 1~20 |
backoff | string | fixed. fixed, linear, exponential 중 하나 | |
initial-delay-seconds | int | 0 이상. 생략하거나 0이면 1초 | |
max-delay-seconds | int | 0 이상. 생략하거나 0이면 상한 없음. 0이 아니면 initial delay 이상이어야 해요 |
0이 아닌 종료 코드, 실행 오류, step 시간 초과가 발생하면 다시 시도해요.
작업이 취소되면 재시도하지 않아요.
재시도 횟수를 모두 소진한 뒤 continue-on-error가 적용돼요.
n번째 재시도(n=1, 2, ...) 전 대기 시간은 fixed에서 initial, linear에서 initial×n, exponential에서 initial×2^(n-1)이에요.
max-delay-seconds가 있으면 먼저 그 값으로 제한한 뒤 0~20%의 무작위 지연을 더해요.
retry:
max-attempts: 3
backoff: exponential
initial-delay-seconds: 2
max-delay-seconds: 20
steps:
- name: deploy
run: ./deploy.sh실행 빈도 제한
limits는 Agent 기기에서 실행 빈도를 제한해요.
서버 호출 레이트 리밋(제한과 정책)과 별도이며 두 제한을 모두 통과해야 실행돼요.
여러 규칙은 모두 통과해야 하고(AND), 같은 type을 두 번 선언할 수 없어요.
| 타입 | 필드와 동작 |
|---|---|
cooldown | after가 필수이며 30s, 10m, 2h, 1h30m 같은 Go duration 형식으로 0보다 커야 해요. on은 success(기본값, 성공한 실행만 계산) 또는 any(모든 실행)예요. capacity·refill과 함께 쓸 수 없어요 |
bucket | capacity는 필수 정수이며 0보다 커야 해요. 몰아서 실행할 수 있는 최대 횟수예요. refill은 필수이며 5/1h처럼 <횟수>/<duration> 형식이에요. after·on과 함께 쓸 수 없어요 |
Agent의 제한 판정은 서버가 작업을 보낸 뒤 비동기로 이뤄져요.
제한에 걸려도 HTTP 429가 아니라 HTTP 201 작업 응답으로 처리돼요.
wait: true로 호출하고 대기 시간 안에 작업이 끝나면 최종 status: "rejected"와 reason: "rate_limited"가 응답에 담겨요.
대기 시간이 끝나면 timedOut: true가 오고 status는 queued 또는 running일 수 있어요.
대기 없이 호출하면 접수 상태만 반환되며, 결과는 consoleUrl의 콘솔 작업 화면에서 확인해주세요.
메시지는 rate limited by <type>; retry after <초>s 형식이에요.
제한에 걸린 작업은 실행되지 않고 거절되며, 다시 실행할 수 있는 시각은 콘솔에 표시돼요.
limits:
- type: cooldown
after: 10m
- type: bucket
capacity: 5
refill: 5/1hforce-allowed는 limits를 건너뛰는 강제 실행을 허용할지 정하고 기본값은 true예요.
false면 강제 실행 요청도 거부돼요.
현재 /v1/run과 콘솔의 지금 실행에는 강제 실행 옵션이 없으므로 이 경로로 들어오는 실행에는 limits가 항상 적용돼요.
로그 보존
Agent가 DEPLITE_LOG_DIR 환경변수를 설정한 경우에만 적용돼요.
워크플로우 작업이 끝나면 해당 로그 디렉토리 전체(다른 워크플로우 로그 포함)에서 최근 수정된 log-retention개 디렉토리만 남기고 나머지를 삭제해요.
DEPLITE_LOG_DIR이 없으면 아무 작업도 하지 않으며, log-retention이 0 이하이면 기본값 50을 사용해요.
환경변수 우선순위
낮은 우선순위부터 높은 우선순위 순서로 적용돼요.
- Agent 프로세스 환경변수 (호스트)
DEPLITE_WORKDIR(Agent가 자동 주입하는 step 작업 디렉토리),TMPDIR·TMP- 워크플로우
env DEPLITE_PARAM_<KEY>(호출의params에서 자동 주입)DEPLITE_SECRET_<KEY>(워크플로우secrets목록의 시크릿)- Step
env
같은 키가 여러 곳에 있으면 아래쪽이 이겨요.
호스트에서 실행되는 step의 기본 셸과 PATH 처리 방식은 스텝 실행 환경에서 다뤄요.
호출 시 주입 변수
| 환경변수 | 의미 |
|---|---|
DEPLITE_PARAM_<KEY> | 호출 시 params.<key> 값. 키는 대문자로 바꾸고 -는 _로 바꿔요 |
DEPLITE_SECRET_<KEY> | 워크플로우 secrets에 선언된 키. Agent 환경변수 DEPLITE_SECRET_<KEY>에서 가져옴 |
DEPLITE_WORKDIR | step별로 새로 생성되는 임시 작업 디렉토리 |
TMPDIR, TMP | DEPLITE_WORKDIR과 같은 값 |
DEPLITE_OUTPUT | step에 id가 있을 때만 주입. 출력 캡처용 파일 경로 (출력 참고) |
DEPLITE_OUTPUT_DIR | 워크플로우 전역 출력 디렉토리. 여기에 result.json을 쓰면 결과로 실려요 |
요청의 ref와 jobId는 환경변수로 자동 주입되지 않아요.
워크플로우에서 ref 값을 사용하려면 params에도 명시적으로 포함해 DEPLITE_PARAM_REF 같은 형태로 전달해주세요.
시크릿
secrets: 배열의 항목은 이름만 적는 문자열과 객체를 섞어 쓸 수 있어요.
secrets:
- DATABASE_URL # 문자열 형태는 required: true가 적용돼요
- name: DEPLOY_KEY
required: true
scope: [deploy] # id가 deploy인 step에만 주입돼요
- name: NOTIFY_WEBHOOK_URL
required: false| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | ✓ | UPPER_SNAKE_CASE. 형식 ^[A-Z][A-Z0-9_]{0,63}$ |
required | bool | 값이 바인딩되지 않았을 때 job을 실패시킬지 | |
description | string | 설명 | |
scope | string[] | 이 시크릿을 볼 수 있는 step id 목록 |
시크릿의 description은 콘솔에 표시돼요.
여기 나열된 이름은 stdout에서 자동 마스킹되고, 어떤 경우에도 서버로 전송되지 않아요.
시크릿 값은 Agent 머신의 환경변수에 DEPLITE_SECRET_DATABASE_URL·DEPLITE_SECRET_API_KEY 형태로 주입해주세요.
scope로 주입 범위 좁히기
scope를 생략하거나 빈 배열로 두면 모든 step에 주입돼요 (기본 동작)- 지정하면 목록에 있는
id를 가진 step에만 주입돼요 id가 없는 step은scope가 지정된 시크릿을 항상 받지 못해요- 주입 형태는 동일하게
DEPLITE_SECRET_<이름>환경변수예요 required검사는scope와 무관하게 워크플로우 단위로 먼저 이뤄져요. 값만 바인딩되어 있으면 scope로 가려진 step이 있어도 통과해요- 마스킹도
scope와 무관하게 바인딩된 모든 시크릿 값에 적용돼요 scope는 서버로 전송되지 않는 Agent 로컬 정책이에요
scope에 적은 step id가 실제로 존재하는지는 검증하지 않아요.
이름을 잘못 적으면 에러 없이 어떤 step에도 주입되지 않고, step은 빈 환경변수로 실행돼요.
출력 (output)
Job의 output을 만드는 방법은 두 가지고, 둘 다 stdout이 아니라 파일이에요.
| 방법 | 주입 변수 | step id | 쓰임새 |
|---|---|---|---|
| 선언형 캡처 | DEPLITE_OUTPUT (step별 파일) | 필요 | key=value로 값을 캡처하고 outputs:에서 타입을 지정해 노출 |
| 자유형 JSON | DEPLITE_OUTPUT_DIR (워크플로우 전역 디렉토리) | 불필요 | result.json에 임의 구조의 JSON. 파일을 결과로 첨부할 수 있음 |
stdout에 JSON을 출력해도 output으로 잡히지 않아요.
stdout·stderr는 로그 스트림(raw)으로만 흘러요.
변수 이름이 DEPLITE_OUTPUT(단수, step별 파일)과 DEPLITE_OUTPUT_DIR(워크플로우 전역 디렉토리)로 한 끗 차이니 헷갈리지 않게 확인해주세요.
Job output은 워크플로우 호출에서 wait: true를 지정하면 응답에 포함돼요.
1. outputs:와 $DEPLITE_OUTPUT
step에 id를 붙이면 그 step에만 DEPLITE_OUTPUT 환경변수가 주입돼요.
값은 해당 작업 전용 임시 디렉토리(DEPLITE_WORKDIR) 안의 파일 경로예요.
이 파일에 값을 적어두면 Agent가 step 종료 후 읽어서 캡처해요.
steps:
- id: build
name: 빌드
run: |
echo "commit=$(git rev-parse HEAD)" >> "$DEPLITE_OUTPUT"
echo "size=42" >> "$DEPLITE_OUTPUT"
outputs:
- name: commit
type: string
from: build.commit
- name: size
type: number
from: build.size파일 포맷
- 한 줄에
key=value하나예요 key는^[a-zA-Z][a-zA-Z0-9_-]{0,63}$형식이에요- 첫
=를 기준으로 자르기 때문에 값 안에=가 들어가도 괜찮아요 =가 없는 줄과 형식에 맞지 않는 key의 줄은 무시돼요 (실패로 처리되지 않아요)- 값은 시크릿 마스킹을 거친 뒤 캡처되고, 파일은 step이 끝나면 읽힌 뒤 삭제돼요
멀티라인 값 문법은 없어요.
GitHub Actions의 구분자(<<EOF) 방식은 지원하지 않으니, 여러 줄 값이 필요하면 DEPLITE_WORKDIR 아래에 파일로 남겨주세요.
outputs로 꺼내기
캡처된 값은 워크플로우 최상위 outputs:를 통해서만 노출돼요.
outputs:를 선언하지 않으면 캡처한 값은 어디에도 실리지 않아요.
| 필드 | 설명 |
|---|---|
name | 워크플로우 결과에 실릴 이름 |
type | string · number · boolean |
from | <step-id>.<key> 형식. 형식이 틀리거나 없는 step id를 가리키면 검증 에러 |
outputs[].name은 영문으로 시작하는 1~64자여야 해요.
캡처된 값은 후속 step의 환경변수로 들어가지 않아요.
GitHub Actions의 steps.<id>.outputs.<key>처럼 다음 step에서 바로 참조할 수 없고, 워크플로우 outputs:에만 투영돼요.
step 사이에 값을 넘기려면 DEPLITE_WORKDIR 아래에 파일을 직접 쓰고 읽어주세요.
2. $DEPLITE_OUTPUT_DIR/result.json
DEPLITE_OUTPUT_DIR은 워크플로우 전체에 주입되는 디렉토리 경로예요.
step id 없이도 쓸 수 있고, 이 디렉토리에 result.json을 쓰면 Agent가 파싱해서 그대로 결과에 실어요.
파일이 없으면 조용히 넘어가요.
- name: report
run: |
cat > "$DEPLITE_OUTPUT_DIR/result.json" <<'JSON'
{"deployedRef":"main-7f3a9b","url":"https://app.example.com"}
JSONresult.json의 최상위는 반드시 JSON 객체여야 해요.
배열이나 스칼라면 결과 병합 자체를 건너뛰어요.
$file 마커로 파일 첨부하기
result.json 트리 안에 {"$file": "<상대 경로>"} 마커를 두면, 해당 파일이 업로드된 뒤 그 자리가 FileRef 객체로 치환돼요.
파일을 결과로 돌려주는 방법은 이것뿐이에요.
- name: build-and-attach
run: |
./build.sh > "$DEPLITE_OUTPUT_DIR/app.apk"
cat > "$DEPLITE_OUTPUT_DIR/result.json" <<'JSON'
{"version":"1.4.0","artifact":{"$file":"app.apk"}}
JSON마커 인식 조건은 다음과 같아요.
- 객체의 키가 정확히 하나이고 그 키가
$file일 때만 치환돼요. 다른 키가 하나라도 같이 있으면 일반 객체로 그대로 실려요 - 경로는
DEPLITE_OUTPUT_DIR기준 상대 경로이고, 대상은 정규 파일이어야 해요 (디렉토리를 가리키면 실패해요) - 배열이나 중첩 객체 안의 마커도 재귀적으로 치환돼요
{ "artifact": { "$file": "report.tar.gz" } } // 치환됨
{ "artifact": { "$file": "report.tar.gz", "note": "x" } } // 치환 안 됨치환된 FileRef 객체는 이런 모양이에요.
{
"__type": "FileRef",
"id": "9f1c…",
"filename": "report.tar.gz",
"contentType": "application/octet-stream",
"size": 20481
}| 필드 | 타입 | 값 |
|---|---|---|
__type | string | 항상 "FileRef" |
id | string | 파일 id. 다운로드에 쓰는 값 |
filename | string | 마커에 적은 경로의 basename만 |
contentType | string | 항상 application/octet-stream |
size | number | 바이트 |
내려받을 때는 id로 GET /v1/storage/files/{id}/download-url을 호출해주세요.
출력 FileRef에는 downloadUrl·expiresAt이 들어 있지 않아서, API를 거치는 것이 유일한 경로예요.
업로드된 파일은 persistent로 저장되어 job이 끝나도 자동 삭제되지 않아요.
contentType은 실제 확장자와 무관하게 항상 application/octet-stream이에요.
이 값으로 파일 종류를 분기하지 말아주세요.
App Deploy(OTA)의 deploy 이벤트에 실리는 입력 방향 FileRef는 downloadUrl을 갖지만, 여기서 다루는 출력 방향 FileRef는 URL이 없어요.
업로드에 실패하면
업로드가 실패해도 job은 실패하지 않아요.
경고 로그만 남고 job 상태는 그대로예요.
업로드에는 job당 10분 타임아웃이 걸려 있고, 초과해도 같은 방식으로 경고만 남기고 진행돼요.
- 마커 하나라도 업로드에 실패하면
result.json트리 전체가output에서 빠져요. 성공한 마커만 골라 담는 부분 성공은 없어요 - 마커가 원래 모양으로 남지도 않아요. 트리 자체가 병합 대상에서 제외돼요
outputs:로 캡처한 값은 영향을 받지 않고 그대로output에 남아요
그래서 호출자 입장에서는 “output은 왔는데 파일 필드만 통째로 없는” 모습이 돼요.
파일이 반드시 필요한 워크플로우라면, 다운스트림에서 해당 필드가 실제로 있는지 확인하도록 만들어두시는 걸 권해드려요.
두 결과의 병합
- 두 경로의 결과는 하나의 Job
output객체로 병합돼요. 별도 필드로 나뉘지 않아요 - 키가 겹치면
result.json쪽이 이겨요 (outputs:결과 위에 덮어써요) - 결과가 비어 있으면
output필드는 아예 전송되지 않아요
검증 규칙
name: 영문 대소문자·숫자·_·.·-만 허용, 1~128자schema-version: 생략하면1이며 현재1만 지원해요. 다른 값이면 해당 파일 로드에 실패해요steps: 1개 이상- 각
step.name: 비어있지 않고, 같은 워크플로우 안에서 중복되지 않음 - 각
step.run: 비어있지 않음 - 각
step.id(선택):^[a-zA-Z][a-zA-Z0-9_-]{0,63}$형식이고, 같은 워크플로우 안에서 중복되지 않음 params: 이름 형식·중복, 타입별options·pattern·min·max,required와default조합을 지켜야 해요 (입력 파라미터 참고)retry:max-attempts는 1~20, 지연 값은 0 이상이며 0이 아닌 최대 지연은 초기 지연 이상이어야 해요 (재시도 참고)limits: type별 필수·허용 필드, duration과 양수 조건을 지켜야 하고 같은 type을 반복할 수 없어요 (실행 빈도 제한 참고)on.webhook: 허용 키는refs,approval이에요.approval의 방식 선언, 하위 키, 절대경로 파일, 파일 형식·키 길이를 지켜야 해요 (실행 승인 참고)- 각
outputs[].from:<step-id>.<key>형식이고, 실제로 존재하는 stepid를 가리킴 on.webhook아래에 알 수 없는 키가 있으면 파일 전체가 로드에 실패해요 (호출 허용 선언 참고)
규칙을 어기면 Agent 시작 시 또는 워크플로우 파일이 다시 스캔될 때 오류 로그가 남고 해당 파일만 건너뛰어요.
해당 워크플로우는 콘솔 목록에서도 사라져요.
실전 레시피 모음
1) DB 야간 백업
PostgreSQL 표준 환경변수(PGHOST·PGUSER·PGPASSWORD·PGDATABASE)를 step에 주입하면 psql 계열 도구(psql·pg_dump 등)가 별도 인자 없이 자동 인식해요.
name: backup-pg
timeout-minutes: 60
secrets:
- PGPASSWORD
- AWS_SECRET_ACCESS_KEY
env:
PGHOST: db.internal
PGPORT: "5432"
PGUSER: backup
PGDATABASE: prod
steps:
- name: connectivity-check
run: psql -c "SELECT 1" > /dev/null
env:
PGPASSWORD: $DEPLITE_SECRET_PGPASSWORD
timeout-minutes: 1
- name: dump
run: pg_dump --no-owner --clean | gzip > /tmp/backup.sql.gz
env:
PGPASSWORD: $DEPLITE_SECRET_PGPASSWORD
timeout-minutes: 30
- name: upload
run: |
aws s3 cp /tmp/backup.sql.gz \
s3://backups/pg/$(date +%F).sql.gz
timeout-minutes: 15
- name: cleanup
run: rm -f /tmp/backup.sql.gz
continue-on-error: true2) Docker 이미지 빌드·푸시·배포
name: deploy-myapp
timeout-minutes: 25
params:
- name: ref
type: string
required: true
env:
IMAGE: registry.example.com/myapp
secrets:
- REGISTRY_PASSWORD
steps:
- name: build
run: docker build -t "$IMAGE:$DEPLITE_PARAM_REF" .
timeout-minutes: 12
- name: push
run: |
echo "$DEPLITE_SECRET_REGISTRY_PASSWORD" | docker login -u deploy --password-stdin registry.example.com
docker push "$IMAGE:$DEPLITE_PARAM_REF"
timeout-minutes: 8
- name: rollout
run: |
kubectl set image deployment/myapp myapp="$IMAGE:$DEPLITE_PARAM_REF"
kubectl rollout status deployment/myapp --timeout=5m
timeout-minutes: 6
- id: report
name: report
run: |
DEP_URL=$(kubectl get ingress myapp -o jsonpath='{.spec.rules[0].host}')
echo "deployedRef=$DEPLITE_PARAM_REF" >> "$DEPLITE_OUTPUT"
echo "url=https://$DEP_URL" >> "$DEPLITE_OUTPUT"
outputs:
- name: deployedRef
type: string
from: report.deployedRef
- name: url
type: string
from: report.url호출 시 params: { "ref": "main-7f3a9b" }로 넘기면 워크플로우에서 $DEPLITE_PARAM_REF로 받을 수 있어요.
3) 외부 API → 데이터 웨어하우스 ETL
name: etl-orders
timeout-minutes: 45
secrets:
- SHOPIFY_TOKEN
- SNOWFLAKE_PWD
env:
WINDOW_HOURS: "24"
steps:
- name: extract
run: |
curl -H "X-Shopify-Access-Token: $DEPLITE_SECRET_SHOPIFY_TOKEN" \
"https://store.myshopify.com/admin/api/2024-01/orders.json?updated_at_min=$(date -d '24 hours ago' -Iseconds)" \
> /tmp/orders.json
timeout-minutes: 15
- name: transform
run: python3 /opt/etl/transform.py /tmp/orders.json /tmp/orders.parquet
timeout-minutes: 10
- name: load
run: python3 /opt/etl/load_snowflake.py /tmp/orders.parquet
env:
SNOWFLAKE_USER: deplite
SNOWFLAKE_ACCOUNT: ab12345.us-east-1
timeout-minutes: 204) 헬스체크 + 자동 복구
name: healthcheck
timeout-minutes: 5
steps:
- name: probe
run: |
if ! curl -fsS https://app.example.com/health > /dev/null; then
echo "UNHEALTHY"
exit 1
fi
echo "OK"
- name: restart-if-failed
run: kubectl rollout restart deployment/myapp
continue-on-error: true서버 측 워크플로우별 제한과 토큰 rate limit은 제한과 정책에서 다뤄요.