Get started

A workflow definition is a Starlark program. AutoFlow runs each submission of it as a workflow: a durable execution on top of autocore that survives restarts and can wait for days. This page takes you from nothing to a completed workflow through the gRPC API, which is the entry point today.

What you need

A running AutoFlow instance with its API listener reachable. The default listener address is 127.0.0.1:8153, plaintext unless a certificate and key are configured.
The API authentication secret: the file api.listen.authentication_secret_file points to, holding a base64-encoded secret. Every call carries a JWT signed with it.
The autoflow CLI, built from the AutoFlow repository with go build ./cmd/autoflow, or grpcurl.

A local sandbox that provisions all of this through Caproni is coming. Follow the AutoFlow on Theseus epic for progress.

The API performs no authorization. Whoever holds the API secret can start any workflow in any namespace. Deciding who may start what is the caller’s job, so treat the secret as a root credential.

Write a workflow definition

Save this as workflow.star:

def main(w, name):
    print("starting for", name)
    sleep(5 * time.second)
    print("slept 5 seconds, still here")
    return "hello, " + name

main is the entry point. Its first parameter w is the workflow context; every further parameter is bound from the arguments the caller sends. sleep is durable: the workflow holds no resources while it waits and resumes even if AutoFlow restarts in between. The value main returns is the workflow’s result.

Start it

AutoFlow serves the AutoFlow gRPC service on its API listener: StartWorkflow, GetWorkflow, CancelWorkflow and SendToWorkflowChannel. The API reference describes every request and response field; the source of truth is internal/module/autoflow/rpc/rpc.proto. The API is subject to change: a new shape is proposed in ADR 0011.

The CLI wraps StartWorkflow and then polls GetWorkflow for you:

autoflow run -s workflow.star --secret-file /path/to/secret \
  --kwarg 'name="world"'

--kwarg and --arg values are Starlark expressions, so strings need their quotes. sensitive("...") marks an argument as a secret the workflow cannot read. Add --address when AutoFlow is not on 127.0.0.1:8153, and --tls or --ca-cert-file for a TLS listener. The namespace defaults to 1.

The command logs Started workflow with the workflow key, the workflow token and the token binding it generated, then Waiting for workflow to complete, and about five seconds later Workflow with state=WORKFLOW_STATE_COMPLETED and the result string_value:"hello, world". Keep the token: the get and cancel commands need it. The exit status is zero only for a completed workflow.

Every call needs a JWT: HS256, audience gitlab-kas, signed with the decoded API secret. The issuer is not validated. This mints one with only the Python standard library:

python3 - /path/to/secret <<'EOF' > jwt.txt
import base64, hashlib, hmac, json, sys, time

secret = base64.b64decode(open(sys.argv[1]).read())

def b64url(b):
    return base64.urlsafe_b64encode(b).rstrip(b"=")

claims = {"aud": "gitlab-kas", "exp": int(time.time()) + 300}
header = b64url(json.dumps({"alg": "HS256", "typ": "JWT"}).encode())
payload = b64url(json.dumps(claims).encode())
signing_input = header + b"." + payload
signature = b64url(hmac.new(secret, signing_input, hashlib.sha256).digest())
print((signing_input + b"." + signature).decode())
EOF

AutoFlow does not serve gRPC reflection, so grpcurl needs the proto sources. From a checkout of the AutoFlow repository, fetch the one external import and build the request:

buf export buf.build/bufbuild/protovalidate -o /tmp/protovalidate

cat > start.json <<EOF
{
  "idempotency_key": "hello-$(date +%s)",
  "workflow_definition": "$(base64 < workflow.star | tr -d '\n')",
  "namespace_id": 1,
  "token_binding": "$(head -c 64 /dev/urandom | base64 | tr -d '\n')",
  "kwargs": [{"name": "name", "value": {"string_value": "world"}}]
}
EOF

grpcurl -plaintext -H "authorization: bearer $(cat jwt.txt)" \
  -import-path . -import-path /tmp/protovalidate \
  -proto internal/module/autoflow/rpc/rpc.proto \
  -d @ 127.0.0.1:8153 \
  gitlab.agent.autoflow.rpc.AutoFlow/StartWorkflow < start.json

workflow_definition is a bytes field, so protobuf JSON carries the script base64-encoded. It is capped at 100 KiB.
token_binding is exactly 64 random bytes. Store it before you call: it is the only way to get the tokens re-issued if you lose the response.
kwargs is a list of {"name", "value"} pairs, not a map, so the binding order is stable across replays. A Value is an object with a single field naming its kind: string_value, integer_value, bool_value, list_value, dict_value, sensitive_string, and so on.
idempotency_key deduplicates per (namespace_id, idempotency_key): re-sending the same key returns the existing workflow instead of starting another.

The response carries workflow_key, workflow_token and, for channels bound to main parameters, channel_tokens.

The workflow token, channel token and token binding returned here are an interim design. Expect them to change once GATE is available.

Read the result

Polling GetWorkflow is the only way to observe a workflow: there is no callback and no streaming variant. The request needs the workflow key, the workflow token and the namespace:

autoflow get <workflow-key> --workflow-token <workflow-token> \
  --secret-file /path/to/secret --wait

{
  "workflow_key": "<workflow-key>",
  "workflow_token": "<workflow-token>",
  "namespace_id": 1
}

The response has state, created_at, updated_at and result. RUNNING is the only non-terminal state. The terminal ones:

State	Meaning
`COMPLETED`	`main` returned. `result` holds its value, or `none_value` without a `return`.
`FAILED`	The workflow failed, for example an action returned an error. `result` is the error.
`CANCELED`	Cancellation was requested and took effect.
`TIMED_OUT`	The schedule-to-complete timeout elapsed, 30 days unless the caller set one.
`SYSTEM_FAILED`	AutoFlow could not run the workflow to completion. Not the workflow definition’s fault.

print output does not travel with the result. It goes to AutoFlow’s log at Info level with sensitive values masked. A stream of it to the caller does not exist yet; issue 953 tracks it.

Next steps

Futures and gather

Every action returns a future; gather is how a workflow waits for the result.

Durable waits

Sleep, timers and select, and why waiting is free.

Call the GitLab API

Reach GitLab from a workflow with the gitlab module.

Policy enforcement

Enforce a policy verdict, and hand the decision to a person when approval is required.

API reference

Every RPC, message and limit.

Last updated on September 12, 2026