Form fields
A button can ask a few questions before it runs: which environment, which version, why now. The answers go to the workflow as inputs, into Jira fields, and into the comment that records the run.
The quickest way to make one is the action builder: add fields, try the form on a sample work item and copy the JSON.
The four field types
Every field has a name, a label and a type. Try each one below and watch what the workflow
would get.
Text: text
One line. For a version, a commit, a URL or a ticket number.
version = "v2.4.1"{ "name": "version", "label": "Version or commit", "type": "text", "maxLength": 40 }Long text: textarea
Several lines. For a reason, release notes or a message to the team.
reason = "QA passed on staging"{ "name": "reason", "label": "Reason", "type": "textarea", "required": true, "maxLength": 300 }Dropdown: select
One choice from a list you set, up to 50 options. For environments, regions or release trains.
environment = "staging"{
"name": "environment",
"label": "Where to",
"type": "select",
"options": ["staging", "qa-eu", "qa-us"],
"default": "staging",
"required": true
}Checkbox: boolean
On or off. For switches like "Run migrations" or "Skip the cache".
migrate = "false"{ "name": "migrate", "label": "Run migrations", "type": "boolean", "default": false }Settings for every field
| Setting | Applies to | Rules | What it does |
|---|---|---|---|
name | all | Letters, digits and _, up to 40, not a digit first | How templates refer to it: {{input.name}} |
label | all | Up to 60 characters | Shown above the field |
type | all | text, textarea, select, boolean | |
required | text, textarea, select | true or leave it out | The Run button won't start the action without a value |
default | all | Text up to 1000, or true/false for a checkbox | What the field starts with |
options | select only | 1 to 50 options, each up to 100 characters | The choices, in order |
maxLength | text, textarea | 1 to 1000, default 500 | Longest answer the field takes |
A checkbox always has a value, so it can't be required. A dropdown's default should be one of its
options; the builder won't let you pick anything else.
Use the answers
Refer to a field with {{input.<name>}} in github.inputs, github.ref or jira.setFields. Every
{{input.…}} must match a field in the same action's form, or the action won't save.
{
"id": "deploy",
"label": "Deploy",
"type": "github_workflow",
"form": [
{ "name": "environment", "label": "Where to", "type": "select", "options": ["staging", "qa-eu"], "required": true },
{ "name": "version", "label": "Version", "type": "text", "required": true, "maxLength": 40 },
{ "name": "migrate", "label": "Run migrations", "type": "boolean" }
],
"github": {
"workflow": "deploy.yml",
"ref": "{{input.version}}",
"inputs": {
"environment": "{{input.environment}}",
"migrate": "{{input.migrate}}",
"issue_key": "{{issue.key}}"
}
}
}Declare them in the workflow
Every answer reaches GitHub as text, so declare each input as type: string. A checkbox arrives as
"true" or "false"; compare it as text.
on:
workflow_dispatch:
inputs:
environment: { type: string, required: true }
migrate: { type: string, required: false, default: 'false' }
issue_key: { type: string, required: true }
cuelight_callback_url: { type: string, required: false }
cuelight_token: { type: string, required: false }
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Migrate
if: inputs.migrate == 'true'
run: ./scripts/migrate.sh
- name: Deploy
env:
ENVIRONMENT: ${{ inputs.environment }}
run: ./scripts/deploy.sh "$ENVIRONMENT"The Workflow YAML tab in the builder writes the inputs, the env block and the
report step for you.
What the person sees
Pressing the button opens the form. Required fields are marked with a star, and Run won't start
the action until they're filled. If the action also has confirm: true or style: "danger", the
button says Continue and a second step asks:
Run "Promote to production" on SHOP-142?
Cancel closes the form without running anything. When it runs, the answers go into the comment on the work item:
▶ Deploy started by Maya Chen. Inputs: environment=staging, migrate=true, version=v2.4.1
Values longer than 100 characters are cut short in the comment. The workflow still gets all of it.
Pre-fill the form from a next step
A workflow that hands back a next step can fill in that step's form, so the next person only
checks it and presses. Use the JSON form of next in the report step:
next: >-
[{"action":"promote-production","inputs":{"reason":"Same build as staging, ${{ github.sha }}"}}]Pre-filled values go through the same checks as typed ones: the field must exist, the value must fit
maxLength, and a dropdown value must be one of its options. The person can still change them.
Limits
- Up to 10 fields per action.
- Up to 50 options per dropdown, each up to 100 characters.
- Answers up to
maxLength(default 500, at most 1000). A rendered workflow input is capped at 1000 characters. - GitHub takes at most 25 workflow inputs. With reporting on, two are Cuelight's, so 23 are yours.
Not supported yet
There's no date picker, number field, multi-select, user picker or file upload. What works today:
| You want | Do this instead |
|---|---|
| A date | A text field labeled "Release date (YYYY-MM-DD)". Check the format in the workflow |
| A number | A text field. Check it in the workflow and fail with a clear message |
| Several choices | One boolean field per choice, or a text field for a comma-separated list |
| A person | {{user.accountId}} or {{user.displayName}} for whoever pressed. A text field for anyone else |
| A file | Attach it to the work item and read it in the workflow through the Jira API, or paste a link |
Need one of these? Tell us on the support page. Requests decide what gets built next.