핵심 개념

Deplite를 구성하는 핵심 개체들을 한 줄씩 정리한 다음, 관계를 그림으로 설명할게요.

Organization

조직이에요. 모든 리소스(Agent, Trigger, Token 등)는 하나의 조직 안에 속해요.
한 사용자는 여러 조직에 동시에 속할 수 있어요.

Membership

사용자가 어떤 조직에 어떤 권한으로 속해 있는지 나타내요.

owner: 모든 리소스 생성·수정·삭제 가능. force 실행 가능.
member: 조회와 일반 실행 가능. 토큰 발급·트리거 생성은 불가.

Agent

당신의 인프라에 설치되는 실행기예요.
하나의 조직에 여러 Agent가 속할 수 있고, 각 Agent는 자기만의 워크플로우 디렉토리를 가져요.

필드	의미
`id`	UUID
`name`	표시명 (`prod-server-01` 등)
`publicKey`	등록 시 Agent가 생성한 ED25519 공개키
`status`	`pending` / `connected` / `disconnected` / `revoked`
`lastSeenAt`	마지막 heartbeat 시각

Workflow

YAML로 정의된 실행 단위예요.
실제 정의는 Agent의 ./workflows/ 안에만 존재해요. 서버는 메타데이터(이름, verbose step, 시크릿 키 이름)만 알아요.

자세한 스펙은 워크플로우 참고.

Trigger

Workflow를 어떻게 실행할지 정의해요.
하나의 워크플로우에 여러 트리거를 붙일 수 있어요.

종류	발동 방식
`webhook`	HTTP POST 호출
`cron`	Cron 표현식에 따른 정기 실행
`slack`	Slack 채널의 메시지/슬래시 명령
`discord`	Discord 채널의 메시지

추가 옵션:

scopeType: workflow(특정 워크플로우만) 또는 agent(같은 Agent의 모든 워크플로우)
responseMode: async(즉시 jobId 반환) 또는 sync(완료까지 대기, timeout 지원)
allowedRefs: 허용할 ref 값 목록 (예: ["main", "release/*"])
allowDebug: debug: true 호출 허용 여부
notify…: 실행 결과를 Slack/Discord로 알림

Job

Trigger 발동 1회당 만들어지는 실행 기록이에요.

필드	의미
`id`	UUID
`status`	`queued` / `running` / `success` / `failed` / `timeout` / `rejected`
`ref`	트리거에서 전달된 ref
`idempotencyKey`	같은 키로 들어오면 중복 제거
`bypassedLimits`	force=true로 우회한 리밋 목록
`output`	워크플로우가 반환한 JSON

API Token

프로그램에서 Deplite API를 호출할 때 쓰는 토큰이에요.
SHA256으로 해시되어 저장되고, 평문은 발급 시점에만 한 번 노출돼요.

스코프 종류:

agent: 특정 Agent들에 명령을 보낼 수 있음
trigger: 특정 Trigger의 webhook을 호출할 수 있음
storage: 파일 스토리지 접근 (read/write/delete 권한 세분화)

선택적으로 분/시간/일당 레이트 리밋을 걸 수 있어요.

Audit Log

조직 내 모든 중요한 동작이 audit log로 남아요.

trigger.run_manual / trigger.force_run
job.dispatch / job.rejected
agent.enroll / agent.revoke
api_token.create / api_token.revoke

metadata 필드에 부가 정보(누가, 어떤 워크플로우, 어떤 ref)가 담겨요.

관계도


Organization ─┬─ Membership (User × role)
              ├─ Agent ─── Workflow* (Agent 디스크에만)
              ├─ Trigger ──→ Workflow (이름으로 참조)
              ├─ Job ──→ Trigger + Agent
              ├─ API Token ──→ Agent[] | Trigger[] | Storage
              └─ Audit Log

엔드투엔드 예시: 야간 백업 시나리오

위 개체들이 실제로 어떻게 협력하는지 한 흐름으로 보여드릴게요.

상황: 매일 새벽 2시에 PostgreSQL을 덤프해 S3에 올리고, 실패 시 Slack 알림을 받고 싶어요.


[1] Organization "acme" 안에 Agent "db-host"를 등록
    Agent → /agent/enroll → agentId=ag-001

[2] Agent의 ./workflows/backup-pg.yaml 작성 (시크릿은 머신 env로 주입)
    name: backup-pg
    secrets: [DATABASE_URL, AWS_SECRET]
    steps:
      - name: dump-and-upload
        run: pg_dump $DATABASE_URL | aws s3 cp - s3://backups/$(date +%F).sql

[3] 대시보드에서 Trigger 생성
    type: cron
    cronExpression: "0 2 * * *"
    cronTimezone: "Asia/Seoul"
    notifyProvider: slack
    notifyOn: failure          ← 실패 시에만 알림

[4] 매일 02:00 (KST)
    Server → SSE deploy 이벤트 (ED25519 서명)
    Agent → 워크플로우 실행 → Job 생성 (status: running)
    Agent → 로그 업로드 (JSONL)
    Agent → 결과 제출 (status: success | failed)
    
[5] Audit Log 자동 기록
    action: trigger.cron_fire / job.dispatch / job.completed

5단계 모두 자동이고, 사람이 손댈 곳은 [2]번 YAML 파일 하나뿐이에요.

다음으로

워크플로우 YAML — 실제 작성 문법
트리거 — 각 트리거 타입 상세