Action Runs

ActionRuns record every execution of a block action in a workspace: core fields, status flow, origins, detail view, access control and retention.

Action Runs

An ActionRun is the execution of a block action in a workspace — for example install, deploy, status or a custom action. The Polycrate API records every execution as a ManagedObject, stores logs and generates activities in the system.

If you want to know "who ran which action on which block, when, and what was the result?" — you query ActionRuns.

Core Fields

Field Meaning
action Name of the executed action (e.g. install)
block FK to the block whose action was run
workspace / organization Context of the execution
user Who triggered the execution
status pending → running → success / failed
log_stdout / log_stderr Complete output of the action (stored in the DB)
exit_code Exit code of the Ansible playbook / block script
start_time / end_time Timestamps — basis for duration metrics

Noteworthy:

  • Logs live in the database. No external log pipeline is needed to retrieve the output of a run.
  • No parent hierarchy: an ActionRun has no WorkflowRun parent. Workflows are currently correlated via activity entries, not via a dedicated parent object.
  • cancelled is not a status: the only permitted end states are success and failed. If a run is hard-aborted, it ends up in failed depending on the cause.

Status Flow

   pending ──▶ running ──▶ success
                     └───▶ failed
  • pending — the run has been accepted but is still queued (e.g. because the responsible agent is currently busy).
  • running — the action is currently running. start_time is set, end_time is not yet.
  • success — the action finished with exit_code=0.
  • failed — the action aborted (exit_code ≠ 0, timeout, agent abort).

Where ActionRuns Come From

An ActionRun is created when an action is started via one of these paths:

  1. UI — action button on a block or its objects.
  2. CLI — polycrate run <block> <action>, provided the workspace is connected to the API.
  3. Operator — the Polycrate Operator invokes an action via API token (e.g. status as a reconciler loop or install on a new K8sApp CR).

Activities in the system:

  • block_action_run_start on start
  • block_action_run_finish after completion (with result)

These activities end up in the activity feed of the workspace and the organization and can be aggregated per minute in the Prometheus export.

Detail View

The detail view of an ActionRun contains:

  • Metadata: who, when, block, action, status, exit code, duration.
  • Logs: stdout and stderr separately, live-streaming by default while the run is still running.
  • Links: to the executed block, to the action definition, to the originating object (e.g. K8sApp if the action was triggered by the operator).
  • Related Activities: activities created before and after the run in the same context.

Typical Use Cases

Troubleshooting after a failed deploy
A deployment fails — the user clicks the last run in the K8sApp detail view and sees stdout/stderr directly in the browser, including the Ansible task trace.
Audit
"Who triggered the uninstall action of the Vault block on Tuesday?" — answered in seconds via the ActionRun list with filters on block, action and time range.
Operator observability
The operator regularly creates status runs per K8sApp. Their duration and success rate are visible via the system metrics and are an indicator of cluster health.

Access Control

  • An ActionRun is scoped via organization and workspace.
  • Anyone with read permission on the workspace sees the list of its ActionRuns.
  • Anyone with read permission on the block may view its stdout/stderr.
  • Starting new actions requires write permission on the workspace (see User Management & RBAC).

Retention

Logs remain stored in the database — no external storage required. A retention policy can be set via management command to automatically archive or delete old runs (see Management Commands).

Related Topics