API

AutoFlow is entered over gRPC. It serves gitlab.agent.autoflow.rpc.AutoFlow on the API listener, the endpoint configured under api.listen and dedicated to GitLab.

Authentication

Every call carries a JWT in the authorization metadata header as bearer <token>.

• Signed with HMAC, as HS256, HS384 or HS512, using the shared secret from api.listen.authentication_secret_file.
• The aud claim must be gitlab-kas.
• The issuer is not validated.

The service performs no authorization on starting a workflow. Whoever holds the shared secret can start any script in any namespace, so deciding who may start what is the caller’s job. Reading, canceling and sending to a workflow are different: each requires that workflow’s own token, which stops one caller from reaching another caller’s workflow.

The service

service AutoFlow {
  // Start a workflow with a caller-supplied Starlark definition and arguments.
  rpc StartWorkflow(StartWorkflowRequest) returns (StartWorkflowResponse) {
    option idempotency_level = IDEMPOTENT;
  }

  // Retrieve a workflow's status and terminal result by its key.
  rpc GetWorkflow(GetWorkflowRequest) returns (GetWorkflowResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }

  // Request cancellation of a workflow by its key. Cancellation is an
  // asynchronous best-effort signal; the workflow transitions to CANCELED on a
  // later replay round.
  rpc CancelWorkflow(CancelWorkflowRequest) returns (CancelWorkflowResponse) {
    option idempotency_level = IDEMPOTENT;
  }

  // Send a value into the channel a channel token addresses. The send is
  // asynchronous and fire-and-forget; the value reaches the workflow on a later
  // replay round.
  //
  // A workflow that is already terminal is refused with FAILED_PRECONDITION,
  // and one that has spent the number of channel values a workflow may receive
  // with RESOURCE_EXHAUSTED. Neither condition ever clears, so the send is
  // refused again however long the caller waits, under the same or a new
  // idempotency key.
  rpc SendToWorkflowChannel(SendToWorkflowChannelRequest)
      returns (SendToWorkflowChannelResponse) {
    option idempotency_level = IDEMPOTENT;
  }
}

StartWorkflow

Submits a workflow definition and starts a workflow for it. The call returns as soon as the workflow is persisted; it does not wait for the workflow to run, and a workflow that later fails does not make StartWorkflow fail.

StartWorkflowRequest

StartWorkflowResponse

Arguments may carry a channel_value with a caller-chosen name at any depth. The workflow receives it as an ordinary channel, and the caller receives a token for it. Nothing checks a name against the script: a name main() never receives still gets a working token, and values sent to it count against the workflow’s limits and are never read.

Tokens

Both tokens are JWTs whose expiry is their exp claim: start time plus the schedule-to-complete timeout plus one hour. That instant is recorded when the workflow is created, so tokens minted later for the same workflow carry it too. Store the workflow token. AutoFlow does not read it back out; the only way to get another is to re-submit under the same idempotency key with the registered binding.

Idempotency

Deduplication is keyed on namespace_id plus idempotency_key.

• Re-submitting a used key returns the existing workflow instead of starting a second one, and mints fresh tokens for it.
• The original submission wins. A different workflow_definition, or different arguments, sent under a used key are ignored. To run new bytes, pick a new key.
• A re-submission that presents a different binding, or none, fails with PERMISSION_DENIED and returns nothing at all, not even the workflow key.
• Channel tokens are minted for the channel names of the retry request, so send the same request on retry.
• Keys starting with __autocore_internal: are reserved and rejected.

GetWorkflow

Reads a workflow by its key. This is the only way to observe progress: there is no callback, no notification and no streaming variant, so a caller that must react to completion polls.

GetWorkflowRequest

GetWorkflowResponse

States

enum WorkflowState {
  WORKFLOW_STATE_UNSPECIFIED = 0;
  WORKFLOW_STATE_RUNNING = 1;
  WORKFLOW_STATE_COMPLETED = 2;
  WORKFLOW_STATE_FAILED = 3;
  WORKFLOW_STATE_CANCELED = 4;
  WORKFLOW_STATE_TIMED_OUT = 5;
  // System failure (abort retry budget exhausted or deterministic internal
  // error), as opposed to WORKFLOW_STATE_FAILED which is a user/business
  // failure returned by the workflow itself.
  WORKFLOW_STATE_SYSTEM_FAILED = 6;
}

CancelWorkflow

Requests cancellation. The request carries the same three fields as GetWorkflowRequest, and the response is empty on purpose: cancellation is an asynchronous best-effort signal. A successful response acknowledges the request only. The workflow moves to WORKFLOW_STATE_CANCELED on a later replay round, which GetWorkflow reports.

SendToWorkflowChannel

Sends one value into one channel of a running workflow.

SendToWorkflowChannelRequest

The response is empty: acceptance is not delivery. The value reaches the workflow when the signal is promoted on a later replay round, and an accepted value is still dropped at promotion if the channel token does not verify. A terminal workflow is refused with FAILED_PRECONDITION, and one that has spent its channel-value budget with RESOURCE_EXHAUSTED; neither condition ever clears.

Rate limit

Each namespace may make 60,000 calls per minute across all four RPCs. A call over the limit is refused with RESOURCE_EXHAUSTED.

Value encoding

args, kwargs, value and result all use Value, a oneof of 18 kinds.

Hashable excludes messages, lists, dicts and sets. A Starlark value of any other type, such as a future or an action, has no encoding here and cannot cross the boundary at any depth.

The autoflow CLI

The autoflow binary in the Relay repository is a thin client over this service. All three subcommands share the connection flags --address (default 127.0.0.1:8153), --secret-file (required, the base64-encoded API secret), --tls and --ca-cert-file. The client signs an HS256 JWT with audience gitlab-kas.

autoflow run -s workflow.star --secret-file /path/to/secret --arg '"hello"'

--arg and --kwarg values are Starlark expressions parsed with the same dialect as a workflow definition, plus a CLI-only sensitive("...") builtin for marking an argument sensitive. run generates a random token binding, prints it with the workflow key and the workflow token, and exits non-zero unless the workflow completed.

More detail

• The AutoFlow API in the design doc.
• internal/module/autoflow/rpc/rpc.proto and pkg/autoflow/value.proto.