Actions

Why?

In mechanical engineering, nobody machines every bolt from scratch. Instead, engineers rely on standardized fasteners: M8 bolts, DIN 912 socket head cap screws, ISO 4762 specifications. These components are defined once, tested rigorously, and reused across countless designs. A turbine blade assembly, a CNC machine frame, a robotic arm—all share the same proven fasteners.

This standardization brings enormous benefits: Engineers don't debug fastener specs; they focus on the actual design challenge.

Actions in Pencilroads serve the same purpose for computational workflows. Instead of copy-pasting scripts between projects, you define an action once—a file converter, a simulation runner, a data validator—and reuse it everywhere. When you improve the action, every workflow that uses it benefits.

Consider a team running workflows:

• Without actions: Each engineer maintains their own Python scripts for converting QBlade output files. Alice's version handles edge cases Bob's doesn't. Carol's script broke last month and nobody noticed. Three slightly different result formats cause comparison headaches.
• With actions: One action, maintained once, tested properly. Every workflow uses it. More collaborative, you could use a public action or a private action from your organization. Plug and play!.

Getting Started

Actions live in your project's directory. Each action is defined by a YAML file that specifies what it does, how it runs and how it is released.

Basic structure

Here's a minimal action that converts simulation output files:

# action.yml
name: 'QBlade Converter'
description: 'Converts QBlade result files to Pencilroads timeseries format'

inputs:
  input:
    description: 'QBlade result file path'
    required: true
  output:
    description: 'Output file path'
    required: true

runs:
  using: 'docker'
  image: 'Dockerfile'

Runtime options

Python

For scripts that don't need complex dependencies:

runs:
  using: 'python3.13'
  main: 'main.py'
  pre: 'setup.py'   # optional: runs before main
  post: 'cleanup.py' # optional: runs after main

Docker

For tools with specific system requirements:

runs:
  using: 'docker'
  image: 'Dockerfile'
  entrypoint: '/app/run.sh'  # optional
  args: ['--verbose']        # optional
  env:                       # optional
    SIMULATION_MODE: 'batch'

Triggering releases

Actions are built into Docker images when their source files change. Define which files trigger a rebuild with the on block:

on:
  commit:
    paths:
      - 'main.py'
      - 'requirements.txt'
      - 'Dockerfile'

When you commit changes to any of these files, Pencilroads automatically rebuilds the action's Docker image.

Using actions in workflows

Reference actions in your workflow steps with the uses keyword:

jobs:
  convert:
    steps:
      - name: Checkout code
        uses: actions/checkout

      - name: Convert results
        uses: qblade/converter
        with:
          input: results/simulation.out
          output: data/timeseries.parquet

Tag or not to tag?

When referencing actions, you can optionally specify a version tag:

uses: qblade/converter        # latest version
uses: qblade/converter@v1.2.0 # specific version

Why you should tag

Reproducibility. A simulation run from six months ago should produce identical results when re-run today. If your workflow uses converter@v1.2.0, it will always use that exact version—even if v2.0.0 exists with breaking changes.

Auditability. For certified engineering work, you need to prove which tools were used. Tags create a clear paper trail: "This analysis used stress-calculator@v3.1.0, validated against test case ASTM-E8."

Controlled upgrades. New action versions might improve accuracy, but you want to validate that improvement before applying it to production workflows. Tags let you upgrade on your schedule.

When not to tag

During active development, always running the latest version makes sense. You're iterating quickly, and pinning versions adds friction. For exploratory work and prototyping, untagged references are practical.

Best practices

• Production workflows: Always tag. Your simulation campaigns, automated reports, and certified analyses should use pinned versions.
• Development workflows: Skip tags during rapid iteration. Pin versions when the workflow matures.
• Shared actions: Use semantic versioning (v1.0.0, v1.1.0, v2.0.0). Document breaking changes between major versions.

Conclusion

Actions are the building blocks of Pencilroads automation. They encapsulate your tools—converters, simulators, validators, processors—into reusable, versioned components.

But actions alone don't run simulations. They need orchestration: which actions run, in what order, with what inputs. That's where workflows come in.

Workflows compose actions into complete pipelines—from raw input files to final reports. A workflow might checkout your model, run preprocessing, execute simulations in parallel across parameter matrices, and aggregate results into a dashboard.

Continue to Workflows to learn how to orchestrate your actions into powerful automation pipelines.