Last updated

Action Scripts

A Run script step runs JavaScript inside an action flow and can call the v2 REST API. Use it when the built-in steps cannot express the logic you need, for example to compute a value, loop over API results, or update several items in one node.

The script never receives an API credential. Windshift mints a short-lived token for the action's executor and applies the same permission checks as a normal API client. A script can never act with more permission than its executor has.

Actions page with create and template controls

Before you start

Scripts run in-process and are intended for trusted authors. Only workspace administrators and action managers should write them. Editing the executable configuration of a privileged action requires the action.set_actor global permission, because a script is delegated code execution. See Global Permissions.

An action that runs as the triggering user uses that user's identity. An action with an actor override uses the override. If neither resolves to an authenticated user, the node fails before it runs.

Add a script node

  1. Open the action in the flow editor.
  2. Add a Run script step.
  3. Enter the JavaScript function body.
  4. Optionally set an Output variable, Timeout (ms), and Max API calls.
  5. Save the action. Saving validates the syntax only. The script does not run while you edit.

Write the script

The source is a function body, not a full program. Use return to produce the node's output. The editor wraps the body in a function and runs it once.

The script has no network, filesystem, shell, module, or async access. It can use:

  • windshift.api.request to call the v2 REST API.
  • console.log, console.info, console.warn, console.error, and console.debug to write bounded lines to the execution trace.
  • The context object and the trigger globals.

Promises, timers, and async/await are not available. Every API call is synchronous.

Call the API

const res = windshift.api.request({
  method: 'POST',
  path: '/items/' + context.item_id + '/comments',
  body: { content: 'Handled by automation', is_private: true }
});

if (!res.ok) {
  throw new Error('comment failed with status ' + res.status);
}

return { comment_id: res.body.data.id };

v2 responses use a data envelope, so a single resource is res.body.data and a list is res.body.data plus res.body.pagination. See Action script examples for complete scripts.

windshift.api.request takes one options object:

Field Required Description
method Yes GET, HEAD, POST, PUT, or PATCH. DELETE is not allowed.
path Yes A path relative to the v2 REST root, for example /items/123.
body No A JSON-serializable value sent as the request body.

The call returns an object:

Field Description
status The HTTP status code.
ok true when the status is 200 to 299.
body The decoded JSON response, or the raw text when the body is not JSON.
truncated true when the response was larger than the per-call cap.

The bridge supplies the credential and every header. The script cannot set an Authorization header, a cookie, a forwarding header, an alternate host, or a redirect target.

Allowed resources

Scripts can reach this initial allowlist of v2 resources:

items, comments, links, link-types, watchers, milestones, iterations, time, users, workspaces, statuses, status-categories, workflows, item-types, priorities, custom-fields, labels, planning, story-points, pages, and attachments.

These resources are deliberately excluded: admin, actions, agent-runs, api-tokens, oauth, mcp, configuration-sets, screens, workspace-roles, packs, assets, and tests. They can mint credentials, delegate identity, or author further automations.

Reads and writes inside the allowlist still require the matching token scope and the executor's own resource permissions.

Allowed writes

Only writes that preserve the action cascade are allowed, so a script-driven change does not restart the automation chain and loop. The permitted mutations are:

Method Path Action
POST /items Create an item.
PATCH /items/{id} Update an item.
POST /items/{id}/transition Move an item through a workflow transition.
POST /items/{id}/comments Add a comment.
POST /items/bulk-transition Move several items through their transitions.

The bulk item routes /items/bulk-update, /items/bulk-patch, and /items/bulk-delete are denied. Reads are not restricted by the write list.

Path rules

The path must start with / and name a v2 resource. Windshift rejects absolute URLs, protocol-relative paths, alternate hosts, URL fragments, escaped paths, and path traversal. A policy violation stops the node and cannot be caught by try/catch.

Execution context

The read-only context object carries a detached view of the execution. It excludes the raw user, item, and event payloads so private trigger content cannot leak into the script.

Field Description
actor_user_id The effective executor's user id.
event_type The trigger event type.
item_id The trigger item id.
workspace_id The trigger workspace id.
trigger_user_id The user who triggered the action.
item A summary of the trigger item: id, key, title, workspace_id, status_id, item_type_id, assignee_id, and priority_id.

The same values are also available as globals: actor_user_id, item_id, workspace_id, and trigger_user_id.

Output

The value you return becomes the node's JSON output. Windshift stores it in the configured Output variable (default script_result). Downstream nodes read that variable with a placeholder such as {{script_result.comment_id}}.

The execution trace also records:

  • api_calls: the number of API calls the script made.
  • console: the captured console lines.
  • console_truncated: true when the console budget was reached.

The output variable must be a simple identifier of at most 64 characters. Reserved names are rejected: windshift, console, context, item_id, workspace_id, actor_user_id, and trigger_user_id.

Budgets and limits

Windshift enforces these limits on every script node. The node settings can narrow them but never widen them.

Limit Default Hard cap
Script source 10 KB 10 KB
Timeout 5000 ms 30000 ms
API calls 50 50
Request body 256 KB 256 KB
Response body per call 256 KB 256 KB
Returned result 64 KB 64 KB
Console output 16 KB, 200 lines, 1 KB per line Same

The operator policy can lower the timeout and the number of concurrent scripts, and can deny the server_scripts capability for the whole instance. See Configuration Options.

Identity, revisions, and attribution

Each run mints one short-lived bearer token for the effective executor, lazily on the first API call. The token expires after 60 seconds and is revoked when the node finishes. The raw token is never written to the definition, the logs, or the trace.

Every save of an action creates a definition revision. Each execution records the revision it ran, so you can see exactly what ran and when. Open the action to browse its revision history. A durable retry reuses the first attempt's revision.

Changing the actor or the executable configuration of an action that has an actor set requires action.set_actor. This applies to the script source and the other executable fields.

Side effects and recovery

Script side effects are not transactional, like every other action node. A script that writes state and then fails has already committed those writes. Windshift persists a write-ahead marker before a mutating call. If the worker stops between a write and the execution log update, the run is marked reconciliation_required instead of running, and automatic replay is blocked. An operator must reconcile the partial write before the action runs again.

Security boundaries

  • The script cannot reach the network, filesystem, shell, modules, or asynchronous APIs.
  • The script cannot choose its own identity, credential, headers, or host.
  • The script cannot reach admin, credential, action-authoring, asset, test, or MCP surfaces.
  • Policy violations are fatal and cannot be swallowed by the script.
  • Scripts share the instance script concurrency limit and are subject to the operator policy.

Test and monitor

Select Test Action to run the action against a chosen item. Open View Logs and select a run to see the execution trace, including each step, the script's console output, the API call count, and any error. The trace shows the definition revision the run used.