Get started

A workflow definition is a Starlark program. AutoFlow runs each submission of it as a workflow: a durable execution on autocore that survives restarts and can wait for days. The gRPC API is the entry point today.

What you need

A running AutoFlow with its API listener reachable, its API authentication secret, and a client. The gitlab-caproni rig, GitLab’s local Kubernetes development environment on Caproni, gives you all three: enable its AutoFlow fragment in caproni.local.yaml and bring the rig up.

extends:
  - fragments/caproni.autoflow.yaml

caproni up

scripts/autoflow.sh in the rig checkout then runs the autoflow CLI against that AutoFlow, with the secret and the address taken care of, and scripts/autocorectl.sh runs autocore’s admin tool in its pod. The rig gained AutoFlow with gitlab-caproni!122.

Against any other AutoFlow instance you need:

Its API listener address. The default 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, or grpcurl. The CLI ships as kas autoflow in every kas binary, the relay image included, so next to a running Relay nothing has to be built. It can also be built from the AutoFlow repository with go build ./cmd/autoflow.

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.

From the rig checkout, scripts/autoflow.sh runs the CLI against the rig’s AutoFlow:

scripts/autoflow.sh run -s workflow.star --kwarg 'name="world"'

The output is the CLI’s, described in the next tab. The workflow’s print lines are in AutoFlow’s log:

caproni kubectl -n autoflow logs deploy/autoflow -c app | grep is_script_print

The CLI calls StartWorkflow and then polls GetWorkflow:

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:

scripts/autoflow.sh get <workflow-key> --workflow-token <workflow-token> --wait

The same JWT and proto sources as for the start:

cat > get.json <<EOF
{
  "workflow_key": "<workflow-key>",
  "workflow_token": "<workflow-token>",
  "namespace_id": 1
}
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/GetWorkflow < get.json

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 29, 2026