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.

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
- Open the action in the flow editor.
- Add a Run script step.
- Enter the JavaScript function body.
- Optionally set an Output variable, Timeout (ms), and Max API calls.
- 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.requestto call the v2 REST API.console.log,console.info,console.warn,console.error, andconsole.debugto write bounded lines to the execution trace.- The
contextobject 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:truewhen 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.
Related documentation
- Action script examples for complete scripts.
- Actions for triggers, steps, and the flow editor.
- Global Permissions for
action.set_actor. - Action Capabilities for HTTP and container runtimes.
- REST API for the v2 resource reference.