Labels

The Labels action adds and removes Confluence labels on the page when it enters a state. It’s the lightweight way to tag pages by where they are in a workflow — marking everything that hits Published with a published label, stripping a draft label on the way out, or rotating a status tag through review.

The action lives in a state’s Actions list in the Workflow Builder. Pick Labels from the action picker; the form has two fields, Add labels and Remove labels, both multi-select label pickers backed by your existing Confluence labels. Either field can be left empty. A single Labels action can do both at once — the usual shape, rotating from one status label to another in the same step.

Behavior

When the action runs, it issues add and remove calls in parallel. There is no guaranteed order between adds and removes inside a single action — if you put the same label in both lists, the result is undefined, so don’t. Splitting the work into two separate Labels actions doesn’t fix this either, since both still run together in the late execution phase. Keep one Labels action per state and don’t list the same label in both fields.

Adding a label that the page already has is a no-op. Removing a label the page doesn’t have surfaces as a per-action error in workflow history, even though the page ends up in the desired state. If you’re rotating labels on a page that may or may not have the source label yet, an occasional error in history is the cost of the simpler config.

Label values are stored verbatim — they are not resolved against variables. Whatever you type into the picker is what gets applied to every page running this workflow. Labels are also lowercased before being saved, matching how Confluence stores them.

The action runs in the late execution phase alongside email, publish, restriction adds, and title edits — after Set official version and Remove restrictions finish. See the actions overview for the full ordering rules.

Interaction with label-based workflow application

Aura supports auto-apply rules that apply a workflow to a page when a matching label is added. The Labels action drives Confluence’s label API, so any add it makes does fire Confluence’s label-added event. The behavior from there is what’s worth understanding.

Auto-apply skips pages that already have a workflow

If your workspace has a rule that applies workflow X to any page tagged needs-review, and a Labels action on a different workflow adds needs-review to a page, the auto-apply check runs but immediately skips the page because it already has a workflow. The page does not switch workflows, and no second workflow is layered on top. This is the deliberate behavior — but it also means you cannot use a Labels action to chain one workflow into another via labels.

The reverse — removing a label that originally applied a workflow — does not affect the running instance. Aura does not listen for label-removed events; auto-apply is a one-shot check at the moment a label is added. Once a workflow is on a page, peeling the trigger label off (by hand, by a Labels action, or through Confluence’s label dialog) leaves the workflow exactly where it is. Pages keep their workflow until someone removes it through the byline’s overflow menu, or until a bulk apply replaces it.

A failed add or remove call shows up in the page’s workflow history under Workflow actions with the underlying message from Confluence. The transition itself is not held up — the page reaches the new state regardless of whether every label change landed. Common causes are removing a label that wasn’t there and labels rejected by Confluence’s name rules. Aura does not retry; the next transition into this state runs the action fresh.

For the surrounding mechanics, see the actions overview and applying workflows.