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.

The workflow gets 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.

The workflow gets reason = "QA passed on staging"
{ "name": "reason", "label": "Reason", "type": "textarea", "required": true, "maxLength": 300 }

One choice from a list you set, up to 50 options. For environments, regions or release trains.

The workflow gets 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".

The workflow gets migrate = "false"
{ "name": "migrate", "label": "Run migrations", "type": "boolean", "default": false }

Settings for every field

SettingApplies toRulesWhat it does
nameallLetters, digits and _, up to 40, not a digit firstHow templates refer to it: {{input.name}}
labelallUp to 60 charactersShown above the field
typealltext, textarea, select, boolean
requiredtext, textarea, selecttrue or leave it outThe Run button won't start the action without a value
defaultallText up to 1000, or true/false for a checkboxWhat the field starts with
optionsselect only1 to 50 options, each up to 100 charactersThe choices, in order
maxLengthtext, textarea1 to 1000, default 500Longest 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 wantDo this instead
A dateA text field labeled "Release date (YYYY-MM-DD)". Check the format in the workflow
A numberA text field. Check it in the workflow and fail with a clear message
Several choicesOne 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 fileAttach 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.