Action references

Who this is for: people and AI assistants who write uses: in a workflow, or publish actions in the company library.

Before you start: read the Steps part of the workflow format.

A step names the action it runs with uses:. The first part of the reference, the owner, says which library the action comes from. There are four forms.

The four forms

Form	Example	What it is
platform/<name>@vN	platform/csv.build@v1	A built-in action, part of Liitora. See Built-in actions.
library/<slug>@vN[.M[.P]]	library/visma.fetch-invoices@v2	An action from our curated platform library. You can use it and read its contract, but not change it. Fork it to adapt it.
<company>/<slug>@vN[.M[.P]]	acme/fetch-devices@v2.1	An action in your company’s own library. <company> is your company’s short name.
workflow/<company>/<name>@vN	workflow/acme/open-service-tickets@v3	Another workflow of your company, called as a step. See Workflow calls.

Rules for the parts:

• The owner uses lowercase letters, digits and -, at most 39 characters.
• The action name uses lowercase letters, digits, ., _ and -, at most 100 characters. It starts with a letter or digit.
• The version starts with v: v2, v2.1 or v2.1.3, without leading zeros. Built-in actions and workflow calls take a major version only (@v1).
• You can only use your own company’s actions and workflows. Another company’s owner name never resolves.

The owner liitora/ was used for curated actions before. It still works and is read as library/, with a note in the run log. Write library/ in new workflows.

How Liitora picks a version

Library actions have versions such as 2.1.3 (major, minor and patch). A pin picks the highest matching version:

Pin	Picks
@v2	the highest 2.x.y
@v2.1	the highest 2.1.y
@v2.1.3	exactly 2.1.3

• Released versions are preferred. A prerelease, such as 2.2.0-beta.1, is used only when no released version matches the pin.
• A deprecated version still resolves, so existing workflows keep running. Its status shows Deprecated in the library, and saving a workflow that uses it gives the warning deprecated_action.
• A pin that matches nothing is a warning when you save (unknown_action), so a draft can be saved first. The workflow can’t be activated until the action exists and you save it again (missing_actions).
• The version is picked when you save the workflow, and that saved version of the workflow always runs exactly that action version. The approval page shows it. This way, what was approved is exactly what runs.
• A new minor or patch version is used after you save the workflow again (no change to the YAML is needed) and approve the new version. The comparison of the two versions shows which action versions changed. To move to a new major version, edit uses:, select Update on the workflow page, or let your AI assistant use the MCP tool upgrade_action_version.

Update available

When a newer version of an action is in the library, the workflow’s Overview shows Update available. For each action it names the version the steps run now and the steps that use it, and offers:

• a compatible update: the newest version with the same major version. It works with your inputs as they are.
• a major update: the newest version with a higher major version, with a list of what changes in a breaking way. Check your with: values against that list first.

Selecting Update to a version saves a new version of the workflow where only the uses: lines of those steps change. Your comments and formatting stay. That new version is like any other change: its tests run, and it goes live only after approval and activation. If the new action version needs inputs your steps don’t give, the update is refused with the reasons and nothing is saved. If someone saved the workflow in the meantime, you get conflict: reload and try again.

You need the Edit workflows permission to update. An AI assistant can list the same updates with the MCP tool list_action_updates.

Status of a version

Each version in the library shows a status:

Status	Meaning
Draft	Saved, but its tests have not passed yet.
Tested	Its own tests pass.
Proven	Its tests pass and it has run well in production. Built-in actions are always proven.
Deprecated	Still works, but should not be used in new workflows.

Publishing a new version of your own action

Versions never change after they are saved. To change an action, publish a new version with a higher number. The same number twice is refused (conflict).

A new version must stay compatible with the version before it in the same major version. These changes need a new major version:

• Inputs (what workflows send): a new required input; a removed input when unknown inputs are refused; an input that accepts less than before, for example a narrower type, fewer enum values, a new pattern, or a stricter minimum, maxLength or other limit.
• Outputs (what later steps read): a removed output; an output that is no longer always there; an output that can return more than before, for example a wider type, more enum values or a looser limit.
• Connection slots: a new required slot, a removed slot, or a slot that now takes another kind of connection.
• Any change to $ref, anyOf, oneOf, allOf, not, if and similar keywords. Liitora can’t compare these safely, so it treats every change to them as breaking.

A new optional input, a new output and a removed enum limit on an input are compatible.

If you make a breaking change in a minor or patch version, the save is refused with major_version_required and the reasons. Publish it as the next major version instead, for example 3.0.0, so workflows pinned to @v2 keep working.

Every new version also passes the script checks. For AI assistants, a password or key written into the script is an error.

Input and output schemas

Each version has an input schema and an output schema in JSON Schema. Liitora checks a step’s input against the input schema before the action runs (invalid_input), and the action’s result against the output schema after it runs (invalid_output). The error names the field and the rule, never the value.

A schema is checked when you save the version, without any network access. The save is refused with validation_failed and a finding that names the schema (input_schema or output_schema) when it breaks one of these limits:

Limit	Code
More than 64 KiB of JSON	schema_too_large
Nested more than 32 levels deep	schema_too_deep
More than 20,000 parts, counting each $ref as the part it points to	schema_too_complex
A $ref that points back into itself	schema_recursive_ref
A $ref to another file or web address, or to a part that doesn’t exist	schema_unsupported_ref

A $ref may point only inside the same schema, for example #/$defs/device. A pattern must be a regular expression without look-arounds or back-references, otherwise the finding is invalid_schema.

Connection slots

A version can name the connections it needs, and the kind of connection each one must be:

{ "erp": { "kind": "visma", "required": true } }

{ "erp": "visma" } is the short form. A step binds each slot to one of your company’s connections:

- id: invoices
  uses: acme/fetch-invoices@v1
  connections:
    erp: visma-production

When you save the workflow, a connection of another kind is an error (connection_kind_mismatch), and so is a connection name that your company doesn’t have (unknown_connection). Before each run, Liitora checks the kind again, in case the connection was deleted and created again with another kind. Only your own company’s connections are ever used.

Forking an action

You can’t publish versions of a built-in or curated action, or change them in any other way (fork_required). Your company’s own actions are visible only to your company. Fork a curated action instead:

1. Open Action library in the app and select the action.
2. Select Fork into our library.
3. Give the copy a short name (lowercase letters, digits, dots, hyphens and underscores) and a name, then select Fork.

The copy is <company>/<short name> in your library. It starts at version 1.0.0, whatever the version you forked, so pin it with @v1. The copy remembers where it came from: its page in the library says Forked from, with the original’s name, version and reference, and links to it. The original stays as it is, and later versions of the original don’t change your copy. An AI assistant can do the same with the MCP tool fork_action.

Next steps

• Built-in actions
• Workflow file format
• MCP tools