Steps Template

A step-based template designed for CI/CD pipelines and multi-stage workflows. Visualizes parallel jobs with a matrix indicator.

Fields

Field	Type	Description
`template`	string	Required. Must be `"steps"`
`progress`	float	Required. Value between `0.0` and `1.0`
`current_step`	integer	Required. Index of the currently running job (0-based)
`total_steps`	integer	Required. Total number of jobs in the workflow
`step_rows`	integer[]	Parallel jobs per step (e.g. `[1,1,3,1]` for a 3-job matrix at step 3). Length must equal `total_steps`. Each value must be between 1 and 10.
`step_labels`	string[]	Optional labels for each step (e.g. `["Build","Test","Deploy"]`). When provided and `total_steps` is 6 or fewer, labels appear below each segment bar. Length must equal `total_steps`. Each label max 32 characters.
`state`	string	Current job name (e.g. "Build Container Image")
`icon`	string	SF Symbol name or MDI icon with `mdi:` prefix (e.g. `"mdi:source-branch"`)
`subtitle`	string	Context subtitle (e.g. "repo / CI/CD")
`accent_color`	string	Named color or hex
`url`	string	Primary URL -- tappable button on the Live Activity (e.g. link to workflow run)
`secondary_url`	string	Secondary URL -- second tappable button (e.g. link to commit)
`background_color`	string	Background color override
`text_color`	string	Text color override

Example Payload

Steps step 3 of 8

{
  "state": "ONGOING",
  "content": {
    "template": "steps",
    "progress": 0.375,
    "state": "Build Container Image",
    "icon": "arrow.triangle.branch",
    "subtitle": "pushward-server / CI/CD",
    "current_step": 3,
    "total_steps": 8,
    "step_rows": [1, 1, 3, 1, 1, 2, 1, 1],
    "step_labels": ["Lint", "Build", "Test", "Scan", "Publish", "Deploy", "Verify", "Notify"],
    "accent_color": "green"
  }
}

Step Rows

The step_rows array defines how many parallel jobs exist at each step. This creates a matrix visualization on the Live Activity:

// [1, 1, 3, 1, 1, 2, 1, 1]
//  Step 1: ●          (1 job)
//  Step 2: ●          (1 job)
//  Step 3: ● ● ●     (3 parallel jobs)
//  Step 4: ●          (1 job)
//  Step 5: ●          (1 job)
//  Step 6: ● ●       (2 parallel jobs)
//  Step 7: ●          (1 job)
//  Step 8: ●          (1 job)

💡 Tip

If step_rows is omitted, every step is treated as a single job. The counter still shows current_step/total_steps.

Typical Flow

Start: Set current_step: 0, progress: 0.0
Each step: Increment current_step, update progress and state with the current job name
End: Set state: "ENDED" with progress: 1.0

Integrations Using This Template

GitHub Actions — maps workflow jobs to steps
Home Assistant — configurable via the template option in entity config