Start with a Git module

Take a module from Git through plan and apply. Your modules and providers stay unchanged — no Takosumi-specific language.

Register a Source

A Source says which repository you track. You only need a workspace, a name, and a URL.

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/sources" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "workspaceId": "ws_example",
    "name": "example-app",
    "url": "https://github.com/example/example-app.git",
    "defaultRef": "v1.2.0",
    "defaultPath": "deploy/opentofu"
  }'

Four options matter. You usually set defaultRef and defaultPath.

Option	Default	Purpose
defaultRef	Git HEAD	the branch, tag, or commit to track
defaultPath	.	the module directory inside the repo
authConnectionId	none	credentials for private repositories
autoSync	false	let the scheduler re-check the ref periodically

The hookSecret in the response is only visible this once. If you set a webhook, save it now. You cannot fetch it again.

Sync

defaultRef says what to track. What actually runs is the commit the ref resolves to — a SourceSnapshot. Sync creates one.

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/sources/src_example/sync" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ "intent": "manual_plan" }'

Wait until the sync Run is succeeded and the snapshot appears under /api/v1/sources/{sourceId}/snapshots. Do not reuse an old snapshot as if it were current — the diff you review would not match what you apply.

Create a Capsule

A Capsule is one deployed unit. If the Source is where from, the Capsule is what is running.

curl -s "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/workspaces/ws_example/capsules" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

Use separate Capsules for dev and prod, and assign a different Connection to each. The same module serves both; only the connection changes.

Plan, then apply

A Run always starts as a plan. Create one, then review it.

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/capsules/cap_example/plan" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

takosumi status run_example
takosumi logs run_example

Apply when the diff looks right. If approval is required, pass /approve first.

curl -X POST "$TAKOSUMI_DEPLOY_CONTROL_URL/api/v1/runs/run_example/apply" \
  -H "authorization: Bearer $TAKOSUMI_DEPLOY_CONTROL_TOKEN"

Next

• Sources and Capsules — the model
• Run model — how Runs behave
• Connect credentials