Takos Docs

テーマ切替

Deploy System ​

Revision: 2026-03-28 current Status: current contract

Takos の current deploy system は repo/ref から app deployment を作る 方式です。旧 docs の build/publish/promote 三段階 CLI は現行 surface ではありません。

実装状況

App deployment API (/api/spaces/:spaceId/app-deployments) のサービス層は現在リファクタリング中で、一部のメソッドが非機能状態です。現時点で動作する deploy パスは lower-level の POST /api/workers/:id/deployments です。rollout service の実装は完了していますが、app deployment パイプラインからの呼び出しが未接続のため、app-deployment API 経由では利用できません。

input ​

app deploy は次を入力に取ります。

  • target space
  • repo ID
  • ref (branch, tag, commit)
  • repo 内の .takos/app.yml
  • manifest が参照する workflow artifact

validation ​

deploy 前に次を検証します。

  • .takos/app.yml が kind: App であること
  • build.fromWorkflow.path が .takos/workflows/ 配下であること
  • service/resource/route 参照が整合していること
  • OAuth auto env や source provenance 変更に approval が必要な場合は caller が承認していること

takos deploy validate は local manifest validation の入口です。

public API / CLI ​

CLI ​

bash
takos deploy --space SPACE_ID --repo REPO_ID --ref main
takos deploy validate
takos deploy status --space SPACE_ID
takos deploy rollback APP_DEPLOYMENT_ID --space SPACE_ID

API ​

text
POST   /api/spaces/:spaceId/app-deployments
GET    /api/spaces/:spaceId/app-deployments
GET    /api/spaces/:spaceId/app-deployments/:appDeploymentId
POST   /api/spaces/:spaceId/app-deployments/:appDeploymentId/rollback
GET    /api/spaces/:spaceId/app-deployments/:appDeploymentId/rollout
POST   /api/spaces/:spaceId/app-deployments/:appDeploymentId/rollout/{pause|resume|abort|promote}
DELETE /api/spaces/:spaceId/app-deployments/:appDeploymentId

deploy の単位 ​

app deployment は次を束ねた snapshot です。

  • repo ID + ref + ref type
  • .takos/app.yml
  • workflow artifact provenance
  • service / route / hostname 更新
  • resource / OAuth / MCP / file handler の reconcile 結果

deploy の最小単位は「bundle 単体」ではなく、manifest と artifact provenance を含む app-level mutation です。

deploy flow ​

text
repo/ref
  -> validate .takos/app.yml
  -> resolve workflow artifact
  -> create/update app
  -> reconcile resources
  -> reconcile services/routes/hostnames
  -> reconcile OAuth / MCP / file handlers
  -> create app deployment record
  -> start rollout if needed

deploy result ​

成功すると少なくとも次が更新されます。

  • app metadata
  • service / route / hostname
  • resource inventory
  • MCP endpoint registration
  • file handler matcher
  • OAuth client metadata
  • app deployment record

internal model ​

control plane の内側では、deploy 結果は service/runtime/route に展開されます。internal では次のような target を扱います。

  • worker-backed service
  • external http-url
  • container host 経由の runtime endpoint

この lower-level model が存在するため、runtime/provider 差分を吸収できます。current manifest contract が直接扱うのは workflow artifact から作る worker-oriented deploy です。container/image 系の lower-level deploy surface は internal/provider-specific な面として残りますが、repo-local app deploy の primary contract ではありません。

rollout ​

rollout state は app deployment ごとに管理されます。current public controls は次です。

  • get rollout state
  • pause
  • resume
  • abort
  • promote

CLI では現在 rollback/list/status を露出し、細かい rollout control は API 側が正本です。

rollback ​

rollback は「前の app deployment へ戻す」操作です。

  • resource を即時に削除する操作ではない
  • schema/data を自動で巻き戻す契約ではない
  • OAuth auto env の差分がある場合は approval が必要になることがある

provider 差分 ​

Takos は Cloudflare を primary surface としつつ、local-platform / Helm / OCI orchestrator 側へ同じ app deploy contract を投影します。provider ごとの差分は Platform Compatibility Matrix と 互換性と制限 を参照してください。

non-goals / historical model ​

current public contract に 含まれない もの:

  • takos build
  • takos publish
  • takos promote
  • top-level takos rollback
  • multi-document package bundle spec
  • tracks / app_environments / immutable release bundle tables を public 正本とする説明

lower-level service deployment route は存在しても、repo-local app deploy の primary documentation contract ではありません。