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

FieldTypeRequiredWhat it does
id2–40 lowercase letters, digits or hyphensYesUnique. Reports and offers refer to actions by id
labeltext, up to 40YesThe button text. Start with a verb: "Deploy to staging"
descriptiontext, up to 140Shown as a tooltip
styleprimary, default, dangerDefault default. danger always asks for confirmation
typegithub_workflow, jira_updateYesWhat pressing the button does
availabilityrules, next-onlyDefault rules. next-only actions only show when a report or offer suggests them
showWhen.projectslist of project keysCase-sensitive, like SHOP
showWhen.issueTypeslist of type namesCase-insensitive, English or your site's language
showWhen.statuseslist of status namesCase-insensitive, English or your site's language
showWhen.labelsAnylist of labelsShows if the work item has any of them
showWhen.labelsNonelist of labelsShows if the work item has none of them
allow.groupslist of Jira group namesWho can press it. Empty means anyone who can see the work item
formlist of fields, up to 10Asked for before the action runs
confirmbooleanAsks "Run … on SHOP-142?" first. Always on for danger
concurrencyper-issue, noneDefault per-issue: one active run of this action per work item
audit.commentbooleanDefault true. Comments on the work item when a run starts and ends
github.repoowner/repoDefaults to the repository mapped to the work item's project
github.workflowfile name or idFor github_workflowLike deploy.yml
github.reftext, templatedDefaults to the mapped project's ref
github.inputsmap of text, templatedWorkflow inputs. Values up to 1000 characters
github.reportbooleanDefault true. Adds cuelight_callback_url and cuelight_token so the run can report back
jira.addLabelslist of labelsFor jira_update
jira.removeLabelslist of labelsFor jira_update
jira.setFieldsmap of field id to text, templatedText, 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

FieldTypeWhat it does
nameletters, digits and underscores, up to 40Used in templates as {{input.name}}
labeltext, up to 60Shown above the field
typetext, textarea, select, boolean
requiredbooleanThe action won't start without a value
defaulttext or booleanPre-filled value
optionslist of text, up to 50Required for select, not allowed otherwise
maxLength1–1000Default 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.

VariableValue
{{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.