Adding version notes to workflow history

Overview

Workflow builders can now add optional notes when publishing a workflow to document what changed and why. Version notes appear in the workflow history table alongside each version, making it easier for teams to understand the evolution of a workflow without having to manually diff versions or ask the original author.

Previously, workflow history showed only timestamps, version numbers, and who published each version. When troubleshooting issues or reviewing changes, teams had to open each version and compare it visually to understand what changed — or rely on memory and Slack threads to recall why a change was made.

Version notes embed that context directly in the version history, creating a living changelog for each workflow.

Add a version note when publishing

When you publish a workflow, you can optionally add a note describing what changed and why.

1. Make your changes to the workflow in the builder.

2. Click Publish to save the workflow version.

3. In the publish dialog, you'll see an optional Publish comment field.

4. Enter a brief description of what changed and why (optional).

   Notes can be up to 5,000 characters long.

5. Click Publish to save the workflow version with the note attached.

   If the workflow is disabled, the dialog offers Publish and enable and Publish without enabling instead. Both save the note.

When you restore a previous version, the restore dialog also has an optional Version notes field, so you can record why the version was restored.

View version notes in workflow history

Version notes appear in the workflow version history table:

1. Open a workflow in the builder.

2. Click the Version History tab in the right-hand panel.

3. The version history table shows each published version with:

   • Version number

   • Publish timestamp

   • Source version

   • A note icon, if a version note was added

4. Click the note icon on a row to expand it and read the note. Click it again to collapse it.

To see who published a version, click the version in the table. Its panel shows Workflow version published with comment, the publish date and time, who published it, and the full note.

Version notes also appear in the workflow's Activity Log, next to each Version published event.

Who can see and add version notes

Anyone with workflow view or edit access can see version notes in the workflow history. Only users with workflow edit permissions (the same as publish permissions) can add version notes when publishing a workflow.

Example uses for version notes

Here are common ways teams use version notes to document workflow changes:

Explain why you made a change:

"Fixed timeout handling per incident #4521 — increased Wait node timeout from 30s to 60s to accommodate slow API responses during peak hours."

Reference related work:

"Added new billing status conditions to support the Q2 subscription pricing changes. See Linear ticket INT-2134 for full context."

Document temporary workarounds:

"Temporary: disabled email notifications for suspended accounts until Marketing approves new messaging templates (expected end of month)."

Provide context for reviewers:

"Refactored error handling across all HTTP nodes to use the new centralized error mapper. No functional changes to workflow behavior."

Track compliance changes:

"Updated data retention logic to comply with new GDPR requirements per Legal review (case #2024-03-15)."

Explain rollbacks:

"Rolled back to v12 — v13 introduced a regression in the subscription status check that caused false negatives."

Example scenario: troubleshooting a failed workflow

A workflow that runs nightly starts failing on Friday morning. The on-call engineer opens the workflow and sees it was last published Thursday afternoon. Without version notes, they would:

1. Open the current version and the previous version side by side

2. Manually diff the two to find what changed

3. Guess why the change was made

4. Slack the person who published it (who may be offline or on vacation)

5. Risk reverting a change that was intentional

With version notes, the history table shows:

Version 12 (published Thu 3:45 PM by Sarah)
"Increased API timeout from 30s to 60s to handle peak hours per Ops request. The API is slower between 2-4 PM and was timing out during nightly runs that overlap with batch processing."

The engineer immediately understands:

• What changed (timeout increased)

• Why it was changed (API performance issue)

• That reverting would re-introduce the timeout problem

• The change was intentional and coordinated with Ops

They investigate the current failure as a new issue rather than assuming the recent publish caused it.

Current limitations

• Not searchable: Version note content is not currently indexed for search. To find a specific note, you must open the workflow and browse the version history table.

• Version-specific only: Notes are attached to published versions only, not to draft saves. If you save a draft multiple times, only the final publish can have a note.

• No notifications: Adding a version note does not trigger notifications. Team members must check the version history or the workflow's Activity Log to see notes.

• Cannot edit after publishing: Once a version is published with a note, the note cannot be edited. If you need to correct or clarify a note, publish a new version with an updated note.