Action Runs and Polycrate API: Every Automation with Audit Log

TL;DR

• Polycrate automatically captures every polycrate run execution as an “Action Run” – including block, action, exit code, timestamp, duration, CLI version, hostname, and OS user.
• Through simple configuration in ~/.polycrate/polycrate.yml, the Polycrate CLI sends these Action Runs to the Polycrate API – without additional logging or audit tooling.
• In the Polycrate API (web UI and HTTP API), you can centrally see who ran which action on which workspace and when, track deployments across workspaces, and selectively re-trigger individual Action Runs. PolyHub is the marketplace for blocks; Action Runs and audit data live in the API.
• The fail-safe design ensures that API issues never block the actual automation – infrastructure changes always proceed, the audit log is “best effort”.
• ayedo connects these API capabilities with proven Platform Engineering approaches to bring automation, compliance, and collaboration together in teams of any size.

Why Action Runs are Crucial for Compliance

“Who restarted the production database on Friday evening?”
“When did version 1.4.3 actually reach production?”
“What changes were made before the incident last night?”

These questions are familiar not only to DevOps teams but also to:

• Linux and Windows admins
• Compliance officers
• Enterprise architects

They must regularly answer these questions – often under time pressure, frequently to auditors, data protection officers, or management.

With plain Ansible, it’s possible but rarely convenient:

• You need additional tools like AWX/Tower or custom-built logging pipelines.
• You must collect, normalize, and store playbook outputs somewhere.
• You lack a unified view across all developer laptops, makeshift scripts, and cron jobs.

Polycrate takes a different approach: Every polycrate run execution is automatically an “Action Run” that, if configured, is reported to the Polycrate API and visible there (web UI / API). No extra setup, no own logging backend.

At the same time, what makes Polycrate strong remains unchanged:

• Ansible and your toolchain consistently run in the container – no local Python/Ansible dependencies, less supply chain risk.
• Your automation is versionable as blocks and shareable via OCI registries and the PolyHub.
• Workspace encryption with age ensures that secrets remain protected despite central audit logs.

In this post, we take a detailed look at Action Runs – from configuration to logged fields to remote re-triggering.

What are Action Runs?

An Action Run is the technical record of a specific execution of:

polycrate run BLOCK ACTION

Whenever you start an action – whether from your laptop, a CI runner, or a makeshift VM – the Polycrate CLI internally creates an Action Run object. This includes, among other things:

• Block name (in the workspace)
• Action name
• Exit code
• Start timestamp
• End timestamp
• Duration
• CLI version
• Hostname
• Operating system user

Optionally, the CLI sends this object to the Polycrate API, which stores it and exposes it in the web UI and via the API.

Important:
This capture is completely independent of your Ansible playbook. Whether you’re patching Linux servers, managing Windows services, or deploying a Kubernetes cluster – the Action Run describes the execution of the Polycrate action, not the technical domain.

This automatically creates an auditable record of all infrastructure changes without needing to implement logging in each playbook individually.

Configuring Polycrate API: ~/.polycrate/polycrate.yml

To ensure Action Runs reach the Polycrate API, configure the CLI once per user in ~/.polycrate/polycrate.yml.

A typical setup looks like this:

# ~/.polycrate/polycrate.yml
api:
  url: "https://api.polycrate.io"        # or your self-hosted endpoint
  api_key: "pc_live_XXXXXXXXXXXXXXXX"    # your personal or robotic API key
  submit_action_runs: true               # send Action Runs to the API

A few points about this:

• api.url points to the Polycrate API instance (SaaS or self-hosted).
• api.api_key is your authentication token. Treat it like a password.
• api.submit_action_runs: true enables sending Action Runs. Without this switch, everything still executes locally, but nothing is sent to the API.
• The Polycrate CLI has no cli.telemetry setting; ayedo does not collect anonymous usage telemetry from the CLI.
• The structure of the configuration file is covered in Configuration and the Polycrate API documentation.

For compliance officers, it’s important:
The API key is personal or clearly assigned to a technical user. This makes it possible to trace back who started the automation in the audit log – regardless of which device was used.

What Exactly is Logged?

Action Runs are deliberately lean but informative. Typical fields include:

• Workspace
  • Name of the workspace
  • Organization (if stored in the workspace)
• Block
  • Name of the block instance in the workspace
  • Reference (from:), including exact block version
• Action
  • Name of the action (e.g. restart, deploy, patch)
• Execution
  • Start time (started_at)
  • End time (finished_at)
  • Duration in milliseconds
  • Exit code
  • Status (successful, failed, aborted)
• Environment
  • CLI version (e.g. polycrate 0.18.3)
  • Hostname (e.g. laptop-max, gitlab-runner-42)
  • Operating system user (e.g. max, gitlab-runner)

From a compliance perspective, especially considering the GDPR, which has been in force since May 25, 2018, two aspects are important:

1. Attributability:
   Through hostname and OS user in combination with the API key, every risky change can be attributed to a person or a service account.
2. Traceability:
   Start time, end time, success/failure, and specific action make every automation step verifiable in hindsight – without having to gather log files from ten systems.

What is not sent:

• Content of your secrets (stored encrypted in the workspace, see below).
• Complete playbook outputs (only metadata, no task log).
• Target host-specific details like IP addresses or configurations, unless you consciously model these as block configuration.

This keeps the audit trail informative without transporting more personal or sensitive data than necessary.

Workspace Encryption and Container Execution as Compliance Building Blocks

From a compliance perspective, it’s crucial that:

• Secrets do not lie in plain text on laptops or CI runners.
• Tools and libraries are reproducible and trustworthy.

Polycrate addresses both:

1. Workspace Encryption with age
   Your sensitive files (API keys, SSH keys, Kubeconfigs) are stored under artifacts/secrets/ in the workspace and encrypted via polycrate workspace encrypt. Details can be found in the documentation on Workspace Encryption.

2. Containerized Execution
   Ansible and the entire toolchain run in a defined container. No “Python 2.7 vs. 3.x” chaos, no wild pip install sprees per laptop, fewer attack vectors. More on this in the Ansible Integration.

For you, this means:
The audit trail over Action Runs comes on top, without needing to invent additional security mechanisms. Polycrate provides the foundation – including clear best practices, see Best Practices.

Action Runs in the Polycrate API: Who, What, When, Where?

Once submit_action_runs is activated, your Action Runs land in the Polycrate API (orchestration and management layer for workspaces, runs, and permissions). In the API UI or via the HTTP API you can answer questions per workspace and organization, for example. PolyHub remains the marketplace for blocks – separate from Action Runs and audit data.

• Who executed the action db-maintenance.restart in workspace acme-prod on Friday at 21:17?
• How many failed deploy runs were there last month?
• On which workspace was the block cargo.ayedo.cloud/ayedo/infra/nginx:0.3.1 last deployed to production?

The API aggregates Action Runs across:

• different workspaces (Dev, Test, Prod),
• various teams and locations,
• laptop, CI, and edge environments.

This allows not only platform teams but also compliance and security officers to see at a glance which automations took place where – without relying on proprietary CI logs, chat histories, or manual change Excel lists.

For structured teams, Action Runs can also be a central element of a Platform Engineering approach: The platform provides standard blocks, and the Action Runs history shows how those building blocks are actually used in practice.

Re-triggering Action Runs: Operations Feature with Added Value

Another advantage of the Polycrate API: You can remotely re-trigger an existing Action Run.

Typical use cases:

• A deployment failed due to a transient error (e.g. timeout against a registry) – instead of piecing together the command again, trigger “re-run” in the Polycrate API.
• A standardized maintenance run (e.g. Windows patching or Linux kernel update) should be repeated in identical form – with the same parameters but at a new time.
• An incident runbook was triggered manually but should be automated to repeat every Sunday – as a bridge until it’s cleanly integrated into a workflow.

Technically, the API uses:

• the stored Action Run record (block, action, workspace context),
• and triggers polycrate run BLOCK ACTION again on a connected runner (e.g. CI or MCP).

Details on API usage and the corresponding endpoints can be found in the Polycrate API documentation.

Important:
Re-triggering does not mindlessly duplicate every change. Your Ansible playbooks remain idempotent (strength of Ansible) and check themselves whether a change is necessary. Polycrate only ensures that you can initiate the identical automation again – traceable and auditable.

Fail-Safe by Design: Action Always Completes

A typical compliance gut feeling: “If we make logging mandatory, the logging server might bring us down.”

Polycrate explicitly solves this dilemma:

• The actual action (Ansible play) always runs locally in the container.
• The transmission of the Action Run to the API is “best effort”:
  • If the API is unreachable, the execution is not aborted.
  • If the API key is invalid, the run continues – you see the error in the CLI output, but your infrastructure remains operable.
  • Network timeouts or TLS issues do not block the automation.

This allows you to activate Action Runs even in sensitive environments where temporary API unavailability must not lead to a halt of maintenance windows or incident runbooks.

Practical Example: Production Database Restart with Audit Log

Let’s look at a concrete example: A block that restarts the production database.

Workspace Setup

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: db-maintenance
    from: db-maintenance
    config:
      env: production
      db_host: db-prod01.acme-corp.com
      db_service_name: "postgresql"

The workspace follows the usual rules, see Workspaces. The block configuration holds only the necessary production-specific values.

A simple inventory for Ansible might look like this:

# inventory.yml (workspace root)
all:
  hosts:
    db-prod01.acme-corp.com:
      ansible_user: "ubuntu"
      ansible_ssh_private_key_file: "{{ workspace.secrets['prod-db.key'] }}"

The inventory lives in the workspace root; Polycrate sets ANSIBLE_INVENTORY automatically. Secrets are protected via workspace encryption.

Block Definition

# blocks/db-maintenance/block.poly
name: db-maintenance
version: 0.1.0
kind: generic

config:
  env: "{{ block.config.env }}"
  db_host: "{{ block.config.db_host }}"
  db_service_name: "{{ block.config.db_service_name }}"

actions:
  - name: restart
    description: "Restart the database service on the target host"
    playbook: restart-db.yml

Values come from the block instance in workspace.poly and are available in templates and playbooks as block.config; cross-block access via workspace.blocks.* is not the intended pattern. Details: Inheritance.

The restart action points to an Ansible playbook in the same directory.

Ansible Playbook

# blocks/db-maintenance/restart-db.yml
- name: Restart database service
  hosts: all
  become: true
  gather_facts: false

  vars:
    db_service_name: "{{ block.config.db_service_name }}"

  tasks:
    - name: Ensure DB host is reachable
      ansible.builtin.ping:

    - name: Restart database service
      ansible.builtin.service:
        name: "{{ db_service_name }}"
        state: restarted

    - name: Check database service status
      ansible.builtin.service_facts:

    - name: Ensure service is running
      ansible.builtin.assert:
        that:
          - ansible_facts.services[db_service_name].state == "running"
        fail_msg: "Database service {{ db_service_name }} is not running"
        success_msg: "Database service {{ db_service_name }} is running"

Important:
hosts: all here means “all hosts from inventory.yml” – Polycrate runs the playbook in the container, but targets are reached via SSH.

Run the Action

The actual run is trivial:

polycrate run db-maintenance restart

What happens?

1. Polycrate starts a container with the configured toolchain (Ansible, Python, SSH).
2. The CLI creates an Action Run object with:
   • Workspace acme-corp-automation
   • Block db-maintenance
   • Action restart
   • Start time, CLI version, hostname, OS user
3. The playbook runs. Ansible provides idempotency.
4. After the run, the CLI updates the Action Run with:
   • End time
   • Duration
   • Exit code
5. If submit_action_runs: true is set, the CLI sends the Action Run to the API.

The answer to the opening question:

“Who restarted the production database on Friday evening?”

You will find it in the Polycrate API by:

• Filtering to workspace acme-corp-automation,
• Selecting block db-maintenance and action restart,
• Setting the time range (“Friday evening”).

With plain Ansible you would need to:

• either use AWX/Tower consistently,
• or build your own logging (callbacks, webhooks, Filebeat shipping),
• or hope someone ran the playbook with --verbose and kept the log.

With Polycrate, this traceability is part of the normal workflow.

Deployment Tracking Across Workspaces

Action Runs help not only with “who did what when?” but also with questions like:

• “When was version 0.3.1 of our web server block last deployed to production?”
• “How long do deployments take on average?”

Because the block reference (from: including version) and the workspace appear in Action Runs, you can for example:

• List all Action Runs for cargo.ayedo.cloud/ayedo/infra/nginx:0.3.1 in workspace acme-prod.
• Generate a deployment history automatically.
• Document audit-style when which version rolled into which environment.

Together with PolyHub and registry integration, you get a full chain:

• A block is built, versioned, and pushed to an OCI registry.
• Workspaces pin an explicit version (never :latest).
• Every polycrate run with that block creates Action Runs – across all workspaces.

The result is a change log for your infrastructure you can inspect anytime – without introducing a separate “deployment tracking” tool.

Compared to Plain Ansible: Where Polycrate Fits

Ansible itself is an excellent automation tool – even without Polycrate. But as soon as you take auditability and team collaboration seriously, many teams hit recurring issues:

• Dependency sprawl: Different Ansible versions, Python environments, and OS packages on laptops and CI runners.
• Playbook sprawl: No consistent block model, hard-to-share automation pieces.
• Fragmented logging: Sometimes logging in CI, sometimes local, sometimes none.

Polycrate addresses this:

• Containerized CLI with a defined toolchain – no local Ansible installs required.
• Block model as a guardrail – reusable, versionable automation pieces shared via PolyHub, see PolyHub docs.
• Action Runs via the API – a continuous audit trail without building separate logging pipelines.

Instead of replacing Ansible, Polycrate makes it a sustainable foundation for your automation – technically, organizationally, and compliance-ready.

Frequently Asked Questions

Do Action Runs store personal data under the GDPR?

Yes, potentially – especially via the personal API key and OS username. That is usually exactly what you want for traceable change management.

What matters:

• API keys should be assigned to people or technical accounts deliberately.
• Role and permission models in your organization must reflect that mapping.
• Polycrate does not store secret contents or full playbook output in Action Runs by default.

Legal classification depends on your organization. Technically, Polycrate offers a clearly bounded dataset you can integrate into your privacy concept.

Do I need the SaaS Polycrate API for Action Runs?

No. The Polycrate API can be self-hosted. You keep all Action Run data in your own infrastructure – often required in regulated industries and under strict GDPR interpretation since May 25, 2018.

The CLI configuration (api.url, api.api_key, api.submit_action_runs) stays the same; only the endpoint changes.

Does sending Action Runs slow down my automation?

In practice, hardly:

• Action Runs are small JSON objects sent over HTTP to the API.
• Overhead is usually in the millisecond range.
• If the API call fails or takes too long, the action still completes (fail-safe design).

If you have extremely latency-sensitive scenarios (e.g. very short IoT/edge cycles), you can disable submit_action_runs for those users or workspaces or use dedicated runners with good API connectivity.

More questions? See our FAQ.

Your Infrastructure, Compliant

Action Runs and the Polycrate API close a gap many teams could only address with heavy extra effort: a continuous, central audit trail for infrastructure automation – without your own logging stacks or proprietary lock-in.

In this post you have seen:

• how to enable the Polycrate API with a few lines in ~/.polycrate/polycrate.yml,
• how every polycrate run is captured as an Action Run,
• which metadata matters for compliance, audit, and security,
• how re-triggering Action Runs helps operations teams day to day,
• and why fail-safe design prevents logging from becoming a single point of failure.

As ayedo, we combine these technical building blocks with proven Platform Engineering concepts: from introducing a block-based automation platform to integrating with existing governance to training for admins and compliance teams.

If you want to see how Action Runs fit your existing automation – on Linux, Windows, IoT/edge, or hybrid environments – good next steps are:

• Polycrate API documentation
• Workshops on Polycrate and automation