Concepts

Cuelight is a loop. A rule puts a button on a work item, someone presses it, the action runs, and what comes back decides which buttons show next.

How Cuelight worksWork item: Rules decide which buttons show. Someone presses a button: Cuelight checks their Jira groups. The action runs: A GitHub workflow or a Jira update. A report or an offer arrives: It says what should happen next. The next steps go back onto the work item.Work itemRules decide which buttons showSomeone presses a buttonCuelight checks their Jira groupsThe action runsA GitHub workflow or a Jira updateA report or an offer arrivesIt says what should happen nextNext steps

Action

A saved, runnable piece of work with a unique id, like deploy-staging. An action either starts a GitHub Actions workflow (github_workflow) or changes the work item in Jira (jira_update). A Jira admin defines all actions in one JSON list. See Actions.

Rule

An action's showWhen says which work items it appears on: projects, issue types, statuses and labels. An action without showWhen appears on every work item, in every project.

Permission

An action's allow.groups lists the Jira groups that can press it. People outside those groups still see the button, disabled, with the reason underneath. See Rules and permissions.

Run

The record of one press: who pressed it, when, with which inputs, which GitHub run it started and how it ended. Every run is stored for 180 days and shown on the Runs tab in Cuelight settings. Unless you turn it off, each run also adds a comment to the work item when it starts and ends.

Report

A message from the running workflow back to Cuelight: the status, a short message, a link, and which actions should come next. The huseyinbuyukdere/cuelight-report GitHub Action sends it in one step. Reports are authenticated with a run token that Cuelight gives the workflow and that expires after 24 hours. See Report API.

Next step

A suggestion that a report or offer leaves on a work item. It points at an action you've defined, can pre-fill that action's form, and expires, after 7 days by default. Next steps show above the rule-based buttons with a note like "Suggested by deploy.yml". A work item holds at most five.

Actions with availability: next-only never show from rules. They only show when a report or offer suggests them, which is how "Roll back staging" appears right after a deploy and nowhere else.

Offer

A next step from work that Cuelight didn't start: a workflow that runs when a pull request opens, an n8n flow, a script, an AI agent. Offers are authenticated with the install key from Cuelight settings → Reporting. An offer can only suggest actions you've defined; it can't change a run or start anything by itself.

State

A work item's current picture: the latest run, its next steps and a summary of the last five runs. Cuelight keeps it in Forge storage and mirrors it to an issue property, so the panel updates while a run is active without a page reload.