Actions
All actions live in one JSON array under Cuelight settings → Actions. The editor checks the
whole list before saving and points at the field that's wrong, like
[2].github.workflow: Required. You can have up to 100 actions.
Rather not write JSON by hand? The action builder makes the same JSON from a form, lets you try the buttons on a sample work item and writes a starting workflow for each one. It also has a prompt for your own AI chat: describe your buttons in one go or let the AI ask, and it writes the JSON. Paste its answer into the builder to check it against these rules before Jira sees it.
Fields
| Field | Type | Required | What it does |
|---|---|---|---|
id | 2–40 lowercase letters, digits or hyphens | Yes | Unique. Reports and offers refer to actions by id |
label | text, up to 40 | Yes | The button text. Start with a verb: "Deploy to staging" |
description | text, up to 140 | Shown as a tooltip | |
style | primary, default, danger | Default default. danger always asks for confirmation | |
type | github_workflow, jira_update | Yes | What pressing the button does |
availability | rules, next-only | Default rules. next-only actions only show when a report or offer suggests them | |
showWhen.projects | list of project keys | Case-sensitive, like SHOP | |
showWhen.issueTypes | list of type names | Case-insensitive, English or your site's language | |
showWhen.statuses | list of status names | Case-insensitive, English or your site's language | |
showWhen.labelsAny | list of labels | Shows if the work item has any of them | |
showWhen.labelsNone | list of labels | Shows if the work item has none of them | |
allow.groups | list of Jira group names | Who can press it. Empty means anyone who can see the work item | |
form | list of fields, up to 10 | Asked for before the action runs | |
confirm | boolean | Asks "Run … on SHOP-142?" first. Always on for danger | |
concurrency | per-issue, none | Default per-issue: one active run of this action per work item | |
audit.comment | boolean | Default true. Comments on the work item when a run starts and ends | |
github.repo | owner/repo | Defaults to the repository mapped to the work item's project | |
github.workflow | file name or id | For github_workflow | Like deploy.yml |
github.ref | text, templated | Defaults to the mapped project's ref | |
github.inputs | map of text, templated | Workflow inputs. Values up to 1000 characters | |
github.report | boolean | Default true. Adds cuelight_callback_url and cuelight_token so the run can report back | |
jira.addLabels | list of labels | For jira_update | |
jira.removeLabels | list of labels | For jira_update | |
jira.setFields | map of field id to text, templated | Text, number and single-select fields only |
A github_workflow action needs a github block and no jira block. A jira_update action needs
at least one of addLabels, removeLabels or setFields, and no github block.
GitHub accepts at most 25 workflow inputs. With github.report on, two of them are Cuelight's, so
you can define up to 23. The names cuelight_callback_url and cuelight_token are reserved.
Form fields
| Field | Type | What it does |
|---|---|---|
name | letters, digits and underscores, up to 40 | Used in templates as {{input.name}} |
label | text, up to 60 | Shown above the field |
type | text, textarea, select, boolean | |
required | boolean | The action won't start without a value |
default | text or boolean | Pre-filled value |
options | list of text, up to 50 | Required for select, not allowed otherwise |
maxLength | 1–1000 | Default 500 |
A next step can pre-fill form fields. The values go through the same checks as typed ones: only
known field names, within maxLength, and only listed options for a select.
Form fields shows each type as people see it, what the workflow receives and what to do for dates, numbers and other types that aren't supported yet.
Templates
github.ref, github.inputs and jira.setFields can use {{path}} placeholders. There's no logic,
filters or functions: the value is inserted as plain text and never evaluated.
| Variable | Value |
|---|---|
{{issue.key}} | SHOP-142 |
{{issue.id}} | Jira's numeric id |
{{issue.summary}} | The work item's summary |
{{issue.type}}, {{issue.status}}, {{issue.project}} | Names and project key |
{{issue.labels}} | Comma-separated labels |
{{issue.fields.<fieldId>}} | Any field as text, like {{issue.fields.customfield_10042}}. Rich text fields, like the description, become plain text |
{{user.accountId}}, {{user.displayName}} | The person who pressed the button |
{{input.<name>}} | A form field. The field must exist in form |
{{run.id}} | Cuelight's run id |
Unknown variables are rejected when you save. A variable that comes out empty at run time becomes an empty string, and the run records a warning. Every rendered value is capped at 1000 characters and stripped of control characters.
Example
This is the configuration behind the demo on the home page and the dev site Cuelight is tested on.
[
{
"id": "deploy-staging",
"label": "Deploy to staging",
"description": "Deploys this work item's changes to staging.",
"style": "primary",
"type": "github_workflow",
"github": {
"workflow": "deploy.yml",
"inputs": {
"environment": "staging",
"issue_key": "{{issue.key}}",
"reason": "{{input.reason}}"
}
},
"form": [{ "name": "reason", "label": "Reason", "type": "textarea", "maxLength": 300 }],
"showWhen": { "projects": ["SHOP"], "issueTypes": ["Bug", "Story"], "statuses": ["In Review"] },
"allow": { "groups": ["qa-team", "developers"] }
},
{
"id": "run-tests",
"label": "Run tests",
"type": "github_workflow",
"github": { "workflow": "tests.yml", "inputs": { "issue_key": "{{issue.key}}" } },
"showWhen": { "projects": ["SHOP"] },
"allow": { "groups": ["qa-team", "developers"] }
},
{
"id": "rollback-staging",
"label": "Roll back staging",
"style": "danger",
"type": "github_workflow",
"availability": "next-only",
"github": {
"workflow": "rollback.yml",
"inputs": { "environment": "staging", "issue_key": "{{issue.key}}" }
},
"allow": { "groups": ["developers", "release-managers"] }
},
{
"id": "promote-production",
"label": "Promote to production",
"style": "primary",
"confirm": true,
"type": "github_workflow",
"availability": "next-only",
"github": {
"workflow": "deploy.yml",
"inputs": {
"environment": "production",
"issue_key": "{{issue.key}}",
"reason": "{{input.reason}}"
}
},
"form": [
{
"name": "reason",
"label": "Reason",
"type": "textarea",
"required": true,
"maxLength": 300
}
],
"allow": { "groups": ["release-managers"] }
},
{
"id": "mark-ready",
"label": "Mark ready to deploy",
"type": "jira_update",
"jira": { "addLabels": ["ready-to-deploy"], "removeLabels": ["blocked"] },
"showWhen": { "projects": ["SHOP"], "labelsNone": ["ready-to-deploy"] },
"allow": { "groups": ["developers"] }
}
]The same five templates are in the action builder. Add from template on the Actions tab inserts ready-made versions of Deploy to staging, Run tests, Roll back, Promote to production and Add label. Each action also has a Test button that reads the workflow file from GitHub and lists inputs it doesn't declare.