Create official version

The Create official version action stamps the page as a named, semantically versioned milestone. It is Aura’s own concept, separate from Confluence’s built-in version history: Confluence numbers every save, while an official version is only created when a workflow deliberately marks one. Most teams use it to record “this is the version that just passed review”, so a Published state is the natural place to put it.

The action carries a single field, Increase by, with three options: Major (1.0.0 -> 2.0.0), Minor (1.0.0 -> 1.1.0), and Patch (1.0.0 -> 1.0.1). Each entry into the state increments the chosen component of the version number and zeroes the components below it. A workflow that stamps a major bump on every approved publish, then a patch bump on a lighter “republish” state, ends up with a clean history of large and small revisions without any per-page bookkeeping.

First run

When the action runs on a page that has no official version yet, the starting point is 0.0.0. Major moves it to 1.0.0, Minor to 0.1.0, Patch to 0.0.1. There is no separate “create initial version” mode — the first run is just an increment from zero, and the option you pick decides which component lands at one. For most workflows that means Major is the right choice on the state where the first official version is born.

Where the version surfaces

The current official version is displayed by the Official version macro, which you embed on the page itself. The macro pulls the latest stamped value live, so it updates the moment the action runs. The full sequence of bumps — every from-version and to-version pair, with actor and timestamp — appears in the page’s workflow history under the Official version event type, and the history filter can narrow the timeline down to just those events. Earlier versions aren’t deleted: each bump is its own history entry, and the page-level value is the most recent one.

Why the action runs early

Actions on a state run in two phases. Create official version is one of the early-phase actions, alongside Remove restrictions, and the late phase only starts once the early phase has finished. The reason is that other actions in the same state often need to talk about the version the state just produced. A Send email in the same Published state can announce the new version in its body because the stamp has already been written by the time the email composes; a Publish page action copying the page into a public space inherits the freshly bumped value. Putting the action in the late phase would make those references race-prone.

The trade-off is that the action increments on every entry, not only on the first one. A state that gets re-entered — for example, a Published state that an On page edit event sends back through review and that approval pushes back into Published — bumps the version every time. This is usually the desired behavior, since each re-entry represents a fresh round of approval, but it does mean a workflow that loops between two states without semantic significance will accumulate version numbers that don’t reflect real revisions.

Every state entry increments

The action is not idempotent. If a workflow can re-enter the same state more than once, expect the version to climb each time. To stamp a version only at certain moments, place the action on a state that is genuinely entered once per release cycle rather than on a high-traffic state with edit-driven loops.

Pairing with page freshness

Page freshness — see Expiration and freshness — is the passive indicator of whether a page has drifted past its last approved version. The official version is its human-readable counterpart: where freshness asks “is this page out of date?”, the official version answers “what was the last good one?”. Embedding the Page Freshness and Official version macros side by side gives a reader both the warning and the reference number, and bumping the version on each successful approval keeps the two in lockstep.

For the broader execution model and the other action types, see the Actions overview.