toki/oto

toki 44f41bdd7c feat: 업데이트된 코드 변경 사항 반영

2026-05-21 17:34:38 +09:00

8.2 KiB

Raw Blame History

OTO CLI

YAML로 정의된 CI/CD 파이프라인을 실행하는 Dart 기반 자동화 도구. Jenkins, FTP, Git, Slack/Mattermost, iOS/Flutter/Android 빌드 등 다양한 작업을 커맨드로 추상화하고, 파이프라인 엔진이 순차 실행한다.

설치

dart pub get
dart compile exe bin/main.dart -o oto

실행 모드

플래그	모드	설명
`-j`	`jenkins`	Jenkins 환경 변수에서 워크스페이스·YAML 읽기
`-t`	`test`	하드코딩된 테스트 데이터로 로컬 실행
`-f <path>`	`file`	지정한 YAML 파일 경로에서 파이프라인 실행
(daemon)	`scheduler`	스케줄러 데몬 모드

oto -j                   # Jenkins CI 모드
oto -t                   # 로컬 테스트 모드
oto -f ./build.yaml      # 파일 기반 실행

실행 흐름

bin/main.dart
  └── Application (singleton)
        └── DataComposer      ← YAML + Jenkins env 파싱
              └── Pipeline
                    └── Command.byType(CommandType) → execute(DataCommand)

YAML 파이프라인 구조

property:
  workspace: /path/to/project
  version: 1.0.0
  env: prod

commands:
  - command: BuildiOS
    id: buildApp
    param:
      workspacePath: <!property.workspace>/ios/Runner.xcworkspace
      scheme: Runner

pipeline:
  id: main
  workflow:
    - exe: buildApp

태그 시스템

태그	방향	설명
`<!property.key>`	읽기	property에서 값 치환
`<@property.key>`	쓰기	커맨드 결과를 property에 저장

태그가 문자열 전체이면 원본 타입(List, Map 등) 유지
태그가 문자열 일부이면 toString() 변환
중첩 접근 지원: <!property.build.version>

파이프라인 흐름 제어

exe — 단순 실행

- exe: buildApp

exe-handle — 성공/실패 분기

- exe-handle:
    id: uploadArtifact
    on-success:
      - exe: notifySuccess
    on-fail:
      - exe: notifyError

if — 조건 분기

- if:
    condition-string: "<!property.env> == prod"
    on-true:
      - exe: deployProd
    on-false:
      - exe: deployDev

지원 연산자: ==, !=, <, <=, >, >=

지원 타입: string, int, float, bool, date, version, object

foreach — 반복

- foreach:
    iterator: <!property.platforms>   # List 또는 Map
    setValue: <@property.target>
    on-do:
      - exe: buildTarget

while — 조건 루프

- while:
    condition-int: <!property.retry> < 3
    on-do:
      - exe: checkStatus

switch — 멀티 케이스

- switch:
    condition-string: <!property.env>
    cases:
    - value: prod
      tasks:
      - exe: deployProd
    - value: dev
      tasks:
      - exe: deployDev

wait-until — 대기

- async: buildStep
- wait-until-string: <!state.buildStep> != complete

async — 비동기 실행

- async: notifyStart    # 완료를 기다리지 않고 다음 단계 진행

커맨드 카탈로그

등록된 커맨드는 Command.specs와 Command.catalogRows가 단일 진실 소스다. 샘플은 assets/yaml/sample/**에서 확인한다.

데이터 모델 구조

모든 커맨드 파라미터는 DataParam을 상속한다.

DataParam
├── workspace?: String          // 기본 작업 디렉토리
├── passExitCodes?: List<int>   // 성공으로 간주할 exit code
├── setResult?: String          // 결과 저장 태그
├── setExitCode?: String        // exit code 저장 태그
└── showPrint?: bool

// 예시
DataBuildiOS extends DataParam {
  xcodeProjectFilePath?: String
  xcworkspaceFilePath?: String
  scheme: String
  configuration?: String
  ...
}

워크스페이스 해석 우선순위:

param.workspace
property.workspace
DataCommon.workspace (Jenkins env)

새 커맨드 추가

1. lib/oto/data/*.dart          DataParam 상속 모델 정의 + @JsonSerializable
2. lib/oto/commands/command.dart  CommandType enum에 값 추가
3. lib/oto/commands/{category}/  Command 상속 클래스 구현
4. Command.register(..., spec: CommandSpec(type: ..., category: ..., dataModel: ..., samplePath: ...))에 구현체 등록
5. lib/oto/commands/command_registry.dart  registerAllCommands()에 등록 함수 연결
6. dart run build_runner build   *.g.dart 생성

등록된 커맨드 목록: Command.catalogRows (category별 정렬)

스케줄러

oto scheduler -r build.yaml       # 스케줄러 등록
oto scheduler -l                  # 목록 조회
oto scheduler -e <alias> true     # 활성화/비활성화
oto scheduler -u <alias>          # 해제

YAML 스케줄러 설정:

scheduler:
  alias: nightly-build
  cron: "0 2 * * *"     # cron 표현식 또는
  # interval: 3600      # 초 단위 interval
  enableLog: true

플랫폼별 실행 메커니즘:

Linux: cron
macOS: LaunchAgent
Windows: Task Scheduler

Roadmap

OTO의 장기 방향은 Jenkins 안에서 실행되는 CLI에 머물지 않고, Edge에 직접 붙는 가벼운 build/deploy agent까지 확장하는 것이다.

Phase 1. CLI 자동화 표면 정리

기존 -j, -f, scheduler 모드는 유지한다.
YAML 파이프라인, 커맨드 확장, 단일 바이너리 배포 구조를 OTO의 핵심 경계로 유지한다.
외부 자동화가 다루기 쉽도록 command catalog, YAML validation, 실행 결과, step event를 구조화된 출력으로 정리한다.
Jenkins는 OTO를 실행하는 호환 경로로 남기되, OTO의 장기 제어면은 Jenkins 전용 환경 변수에 종속시키지 않는다.

Phase 2. Edge bootstrap 기반 `oto-agent`

Edge에서 먼저 OTO agent를 생성하고, 대상 머신에서 실행할 bootstrap command를 발급하는 Jenkins node 연결식 UX를 목표로 한다.
대상 머신은 bootstrap command 실행만으로 OS/arch에 맞는 OTO 바이너리를 설치하고 agent 설정을 생성한다.
폐쇄망과 개발망을 고려해 HTTPS를 기본 권장하되, HTTP local/insecure 모드도 명시적으로 지원한다.
TLS를 강제하지 않는 환경에서는 one-time bootstrap token, Edge fingerprint 또는 public key pinning, 바이너리 checksum/signature 검증을 agent 등록 계약에 포함한다.
설치 후 oto-agent는 iop-node를 거치지 않고 Edge에 직접 outbound 연결한다.

Phase 3. 메시지 기반 빌드 에이전트

oto agent 또는 oto daemon 모드에서 Edge와 proto-socket 기반 양방향 메시지 통신을 사용한다.
OTO는 Edge 입장에서 build/deploy 전용 domain agent이며, generic node의 하위 실행물이 아니다.
기본 메시지 범위는 agent register, capabilities, run request, step event, log stream, artifact event, cancel, status, self-update를 우선한다.
YAML 파이프라인과 커맨드 확장 모델은 그대로 유지하고, agent 모드는 이를 원격 제어 가능한 실행 표면으로 노출한다.

프로젝트 구조

lib/
├── cli/                         # CLI 인자 파싱, 스케줄러 관리
└── oto/
    ├── application.dart         # 싱글턴 오케스트레이터
    ├── commands/                # 커맨드 구현체 (카테고리별)
    ├── core/                    # 태그 시스템, 데이터 합성, 정의 데이터
    ├── data/                    # JSON 직렬화 데이터 모델 (*.g.dart 포함)
    ├── pipeline/                # 파이프라인 흐름 제어 엔진
    └── utils/                   # 공통 유틸리티

기술 스택

언어: Dart (SDK >=2.18.6 <4.0.0)
의존성: dart_framework (커스텀), http, json_annotation, cron, xml
코드 생성: json_serializable + build_runner

dart run build_runner build      # 데이터 모델 생성

에러 처리

Application.build()는 catch (e, stacktrace)로 Exception과 Error 모두 처리
실패 시 BuildResult.failure(..., exitCode: 10)을 반환하고 CLI가 부모 프로세스에 exit code 전달
passExitCodes로 성공으로 간주할 exit code 지정 가능

8.2 KiB Raw Blame History