Connections

Overview

A workflow that clones a repository, opens a pull request or posts a refund acts through a connection - a GitHub, Stripe or Linear account connected to the agent or to its organisation. Rather than freezing a connection id into the source, declare each connection once by key and reference the key. At run time the engine resolves the key against the connections of the agent the run belongs to, so one definition runs unchanged on a hand-built agent, a duplicated agent and a template install.

export const ticketToPr = createWorkflow({
  name: 'ticket-to-pr',
  inputSchema: z.object({ ticketId: z.string(), repo: z.string(), baseRef: z.string().default('main') }),
  connections: [{ key: 'github', integrationType: 'github', required: true }],
  workspace: {
    kind: 'git',
    repo: template('input.repo'),
    ref: template('input.baseRef'),
    credentialsRef: 'github',          // the key, not a connection id
  },
})

Declaring connections on createWorkflow, and the compile-time check described below, ship with the next lua-cli release (after 3.31.0). Run-time resolution, the connection.resolved event and the push-time refusal are live on the platform, and agent templates already declare keys the same way.

Declaring connections

connections on createWorkflow is a list of declarations:

Field	Type	Notes
`key`	`string`	`^[a-z][a-z0-9_-]{0,63}$`, unique within the workflow. The name `credentialsRef` and `requiredConnections` use.
`integrationType`	`string`	The integration the key stands for - `'github'`, `'stripe'`, `'linear'`, … Only connections of this type are candidates when the key is resolved.
`required`	`boolean`	Documents that the workflow cannot run without it.
`description`	`string`	What the connection is used for; shown to whoever connects the account.

The declarations ride with every pushed version of the workflow and are not part of the graph hash, so adding one does not change the workflow’s topology.

Using a key

A declared key can stand anywhere a connection id is accepted:

Where	What the key does
`workspace.credentialsRef`	Names the git-host connection that mints the checkout token for Job-tier steps. See Job tier.
`requiredConnections` on a code, agent or tool step	Connections the step must be able to use. The engine checks each one before the step is dispatched.
`toolScope.connectionIds` on a Job-tier agent step	Connections mounted into the coding turn as MCP servers. The bound ids are what the turn’s proxy mounts; a key that does not bind closes the scope.

The step code itself calls the integration the same way it always has - Integrations.passthrough('stripe', ...) names the integration, not the key.

Example

A refund workflow that declares its Stripe connection once and posts the refund through it after an approval:

import { z } from 'zod';
import { createStep, createWorkflow, template, Integrations } from 'lua-cli';

const postRefund = createStep({
  id: 'postRefund',
  inputSchema: z.object({
    approved: z.boolean(),
    editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
    input: z.object({ ticketId: z.string(), amount: z.number() }),
  }),
  outputSchema: z.object({ refundId: z.string().nullable() }),
  sideEffects: 'external',
  onError: 'park',
  requiredConnections: ['stripe'],          // the declared key below
  async execute({ inputData }) {
    if (!inputData.approved) return { refundId: null };
    const r = inputData.editedPayload ?? inputData.input;
    const res = await Integrations.passthrough('stripe', {
      method: 'POST',
      path: '/v1/refunds',
      headers: { 'Idempotency-Key': `refund:${r.ticketId}` },
      body: { charge: r.ticketId, amount: r.amount },
    });
    return { refundId: res.body.id };
  },
});

export const refund = createWorkflow({
  name: 'refund-approval',
  inputSchema: z.object({ ticketId: z.string(), amount: z.number(), requesterId: z.string() }),
  outputSchema: z.object({ refundId: z.string().nullable() }),
  budget: { maxDurationSeconds: 14 * 24 * 3600 },
  connections: [{ key: 'stripe', integrationType: 'stripe', required: true }],
})
  .approval('approveRefund', {
    title: 'Refund request',
    details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
    approver: { role: 'support-lead' },
    excludeInitiator: true,
    timeoutHours: 8,
    onTimeout: 'deny',
    editable: true,
    editablePaths: ['amount'],
    editedPayloadSchema: z.object({ ticketId: z.string(), amount: z.number().positive().max(500) }),
  })
  .then(postRefund)
  .commit();

Push it to any agent that has a Stripe connection and it runs. Push it to one that does not, and the postRefund step parks with a notice naming the key and the integration to connect (below).

How a key is resolved

When a run first needs a key, the engine picks one connection:

The candidates are the connections of the declared integrationType that belong to the agent the run is on, plus the organisation’s. A person’s own connection is never a candidate - a run acts as the agent, not as a user.
Agent-scoped candidates win. Org-scoped ones are consulted only when the agent has none of that type.
One candidate is chosen. With several, the one whose account label equals the key is chosen; otherwise the step fails as ambiguous (below).

A key is resolved once per run, the first time any step needs it, and every later step reads the same id - a connection added mid-run does not change a run already under way. The choice is appended to the run’s events:

{
  "type": "connection.resolved",
  "data": { "key": "stripe", "connectionId": "66f1c2...", "scope": "agent", "integrationType": "stripe" }
}

It is also stamped on the run: lua workflows status <runId> --steps --json returns the resolutions under data.connections (key, connectionId, integrationType, scope, at), and from the next CLI release lua workflows status <runId> prints them as a Connections: line (stripe → 66f1c2... (stripe, agent)).

When resolution fails

Situation	Step error	What to do
No connection of that type on the agent or its organisation	`credentials_unresolved` - Connect a stripe connection to this agent (or its org) for connection key ‘stripe’, then retry the step.	Connect the integration, then retry the step.
Several connections of that type and none labelled with the key	`credentials_unresolved`, listing the candidates - Connection key ‘stripe’ matches several stripe connections on this agent - label the one to use ‘stripe’ (candidates: …), then retry the step.	Set one connection’s label to the key, then retry.
The connection resolved but cannot mint a token or be mounted	`credentials_revoked` (unchanged)	Re-authorise the connection, then retry.
The connection roster could not be reached	A transport fault, retried automatically: a worker-tier step waits (`step.throttled`); a Job-tier step fails `job_spawn_failed` as transient before any container is created and is re-armed.	Nothing - the retry resolves the key once the roster answers.

credentials_unresolved is not retried automatically and no model turn is billed for it. The step’s onError decides what the run does: with onError: 'park' the run waits on an exception gate, so the connect-then-lua workflows retry-step loop resumes it without losing completed work. The run’s events also carry a run.log notice naming the key and the integration to connect.

Resolution applies only to values that are declared keys. A value that is a connection id never enters the resolver: it is mounted or minted exactly as before, and a workflow with no connections block behaves exactly as it did.

Push-time validation

lua push workflow refuses a credentialsRef or requiredConnections entry that looks like a key but is not declared - with or without a connections block - and lua compile refuses it the same way from the next CLI release:

connection-key-undeclared: workspace.credentialsRef 'github' is neither a connection id nor a declared
connections[].key — declare it: connections: [{ key: 'github', integrationType: '<catalog slug, e.g. github>' }]
and it resolves on any agent

The message names the path and the exact declaration to add. A malformed declaration (a key outside the grammar, such as GitHub) is connection-declaration-invalid. Literal ids keep working. A connection id - a 24-character hex id, or an id with a provider prefix - is not a key: it passes the compile as before and the server verifies it at push. Only a lowercase slug that is not declared fails, which is the shape that was already broken at run time. Templates are unchanged. An agent template declares connections[].key the same way, and an install binds each key to the installer’s connection; that binding still wins. Run-time resolution is the fallback for a definition that reaches the engine with an unbound key.

Job tier - how a credentialsRef becomes a short-lived token for the checkout
Authoring - the connections field and the requiredConnections step option
Runs and events - where connection.resolved appears
Workflows Command - the Connections: line on status

Getting Started

Core Concepts

Workflows

CLI Commands

API Reference

Template & Examples

Overview

Declaring connections

Using a key

Example

How a key is resolved

When resolution fails

Push-time validation

​Overview

​Declaring connections

​Using a key

​Example

​How a key is resolved

​When resolution fails

​Push-time validation

​Related

Overview

Declaring connections

Using a key

Example

How a key is resolved

When resolution fails

Push-time validation

Related