Skip to Content
문서YAML 스펙

워크플로우

이 문서는 워크플로우 YAML의 모든 필드를 다뤄요.
입문자라면 워크플로우 생성부터 보시는 게 좋아요.

파일 규칙

  • 위치: Agent의 워크플로우 디렉토리 (기본 ./workflows/, DEPLITE_WORKFLOWS_DIR로 오버라이드 가능)
  • 확장자: .yaml 또는 .yml
  • 파일이 추가·수정·삭제되면 Agent가 파일시스템 이벤트로 즉시 감지해서 반영해요

최상위 필드

필드타입필수기본값설명
namestring✓—워크플로우 식별자. 영문 대소문자·숫자·_·.·-만 허용, 1~128자
stepsobject[]✓—최소 1개
timeout-minutesint전체 워크플로우 timeout (지정 시 step 전체에 적용)
envobject{}모든 step에 적용되는 환경변수
secretsstring[][]Agent 프로세스의 DEPLITE_SECRET_<KEY> 환경변수에서 가져와 마스킹할 시크릿 이름 목록

Step 필드

필드타입필수기본값설명
namestring✓—워크플로우 안에서 고유해야 해요
runstring✓—실행할 셸 명령 (multi-line 가능)
verboseboolfalsedebug 실행 대상 step 표시 (아래 참고)
timeout-minutesint(워크플로우 값 상속)step별 timeout
working-directorystring(Agent 작업 폴더)cd 후 실행
envobject{}step별 환경변수
shellstring(Agent 기본 셸)이 step만 다른 셸로 실행할 때 사용
continue-on-errorboolfalse실패해도 다음 step 진행

시크릿 값은 stdout/stderr에 노출되어도 ***로 자동 마스킹돼요.

verbose: true 동작

step에 verbose: true를 선언하면, 트리거를 debug: true로 호출했을 때 해당 step의 원본 stdout/stderr가 그대로 서버에 전송돼요.
워크플로우 안의 어느 step도 verbose: true로 선언되지 않으면 debug: true 호출 자체가 거절돼요.

환경변수 우선순위

낮은 우선순위부터 높은 우선순위 순서로 적용돼요.

  1. Agent 프로세스 환경변수 (호스트)
  2. DEPLITE_WORKDIR (Agent가 자동 주입하는 step 작업 디렉토리), TMPDIR·TMP
  3. 워크플로우 env
  4. DEPLITE_PARAM_<KEY> (트리거의 params에서 자동 주입)
  5. DEPLITE_SECRET_<KEY> (워크플로우 secrets 목록의 시크릿)
  6. Step env

같은 키가 여러 곳에 있으면 아래쪽이 이겨요.

트리거 주입 변수

환경변수의미
DEPLITE_PARAM_<KEY>트리거 호출 시 params.<key> 값 (대문자로 변환)
DEPLITE_SECRET_<KEY>워크플로우 secrets에 선언된 키. Agent 환경변수 DEPLITE_SECRET_<KEY>에서 가져옴
DEPLITE_WORKDIRstep별로 새로 생성되는 임시 작업 디렉토리
TMPDIR, TMPDEPLITE_WORKDIR과 같은 값

트리거의 ref·debug·jobId는 환경변수로 자동 주입되지 않아요.
워크플로우에서 받고 싶다면 트리거의 params에 명시적으로 포함해서 호출하면 DEPLITE_PARAM_REF 같은 형태로 받을 수 있어요.

시크릿

secrets:
  - DATABASE_URL
  - API_KEY

여기 나열된 이름은 stdout에서 자동 마스킹되고, 어떤 경우에도 서버로 전송되지 않아요.
시크릿 값은 Agent 머신의 환경변수에 DEPLITE_SECRET_DATABASE_URL·DEPLITE_SECRET_API_KEY 형태로 주입해주세요.

출력 (output)

마지막 step에서 stdout으로 단일 라인 JSON을 출력하면 Job의 output 필드로 저장돼요.

- name: Deploy
  run: |
    DEP_ID=$(deploy.sh)
    echo "{\"deploymentId\":\"$DEP_ID\",\"url\":\"https://app.example.com\"}"

대시보드와 API 응답에서 이 JSON을 그대로 받을 수 있어요.

검증 규칙

  • name: 영문 대소문자·숫자·_·.·-만 허용, 1~128자
  • steps: 1개 이상
  • 각 step.name: 비어있지 않고, 같은 워크플로우 안에서 중복되지 않음
  • 각 step.run: 비어있지 않음

규칙을 어기면 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: true

2) Docker 이미지 빌드·푸시·배포

name: deploy-myapp
timeout-minutes: 25
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
  - name: report
    run: |
      DEP_URL=$(kubectl get ingress myapp -o jsonpath='{.spec.rules[0].host}')
      echo "{\"deployedRef\":\"$DEPLITE_PARAM_REF\",\"url\":\"https://$DEP_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: 20

4) 헬스체크 + 자동 복구

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

서버 측 트리거의 쿨다운·동시 실행 제한은 제한과 정책에서 다뤄요.

5) 디버그 환경 임시 부팅 + verbose

debug 모드로 호출할 step에 verbose: true를 붙여 두면, 트리거를 debug: true로 부를 때 원본 로그가 그대로 전송돼요.

name: spin-up-debug
timeout-minutes: 15
steps:
  - name: launch
    verbose: true
    run: |
      ID=$(docker run -d --rm -p 0:3000 myapp:debug)
      HOST_PORT=$(docker port "$ID" 3000 | awk -F: '{print $2}')
      echo "{\"containerId\":\"$ID\",\"url\":\"http://debug.internal:$HOST_PORT\"}"

Webhook으로 호출 → 응답의 output.url을 그대로 Slack에 던질 수 있어요.

관련 문서

트리거Webhook·Cron·Slack/Discord 비교와 옵션제한과 정책서버 측 트리거 쿨다운·토큰 rate limit
최종 수정 일자:
CLI트리거