Workflow patterns

Small, complete examples for things teams ask about most. Each one shows the action JSON and the workflow change it needs. For a whole flow put together, see the walkthrough.

Offer different steps on success and failure

Use two report steps with if: success() and if: failure(). Only one of them runs.

- name: Report success
  if: success()
  uses: huseyinbuyukdere/cuelight-report@v1
  with:
    status: success
    message: Deployed to staging
    next: rollback-staging, promote-production

- name: Report failure
  if: failure()
  uses: huseyinbuyukdere/cuelight-report@v1
  with:
    status: failure
    message: Deploy failed before anything changed
    next: deploy-staging

Offering the same action again after a failure, here deploy-staging, gives people a one-press retry. It shows under Next steps even if the rules wouldn't show it right now.

Show progress while it runs

Send status: running as often as you like. The panel updates its message each time, without a page reload.

steps:
  - name: Build
    run: npm run build
  - uses: huseyinbuyukdere/cuelight-report@v1
    with: { status: running, message: 'Built. Running migrations (1/2)' }
  - name: Migrate
    run: ./scripts/migrate.sh
  - uses: huseyinbuyukdere/cuelight-report@v1
    with: { status: running, message: 'Migrated. Switching traffic (2/2)' }
  - name: Switch traffic
    run: ./scripts/switch.sh
  - if: always()
    uses: huseyinbuyukdere/cuelight-report@v1
    with:
      status: ${{ job.status }}
      message: Release finished

Ask for input before it runs

A form asks the person pressing the button. Pass the answers to the workflow with {{input.<name>}}. Form fields covers every field type and its limits.

{
  "id": "deploy",
  "label": "Deploy",
  "type": "github_workflow",
  "form": [
    {
      "name": "environment",
      "label": "Where to",
      "type": "select",
      "options": ["staging", "qa-eu", "qa-us"],
      "default": "staging",
      "required": true
    },
    { "name": "migrate", "label": "Run migrations", "type": "boolean", "default": false },
    { "name": "note", "label": "Note for the team", "type": "textarea", "maxLength": 200 }
  ],
  "github": {
    "workflow": "deploy.yml",
    "inputs": {
      "environment": "{{input.environment}}",
      "migrate": "{{input.migrate}}",
      "note": "{{input.note}}",
      "issue_key": "{{issue.key}}"
    }
  }
}

Every input reaches the workflow as text, so a boolean arrives as "true" or "false":

on:
  workflow_dispatch:
    inputs:
      environment: { type: string, required: true }
      migrate: { type: string, required: false, default: 'false' }
      note: { type: string, required: 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

Run on the work item's branch

If your branches are named after work items, like SHOP-142 or feature/SHOP-142, set github.ref with a template. The workflow runs the code on that branch.

{
  "id": "run-tests",
  "label": "Run tests",
  "type": "github_workflow",
  "github": {
    "workflow": "tests.yml",
    "ref": "feature/{{issue.key}}",
    "inputs": { "issue_key": "{{issue.key}}" }
  }
}

The workflow file must still exist on the default branch; GitHub only starts workflow_dispatch workflows that are there. If the branch doesn't exist, the run doesn't start and the panel shows GitHub's reason.

Pre-fill the next step's form

A report can fill in the next action's form, so the next person only has to check it and press. Use the JSON form of next:

- name: Report
  if: success()
  uses: huseyinbuyukdere/cuelight-report@v1
  with:
    status: success
    message: Staging is on ${{ github.sha }}
    next: >-
      [{"action":"promote-production","inputs":{"reason":"Same build as staging, ${{ github.sha }}"}}]

The values go through the same checks as typed ones: the field must exist in the action's form and fit its maxLength. The person pressing can still change them.

Report once from a workflow with several jobs

job.status only knows about the job it's in. Add a last job that waits for the others and reports their combined result:

jobs:
  build: { runs-on: ubuntu-latest, steps: [{ run: npm run build }] }
  test: { runs-on: ubuntu-latest, needs: build, steps: [{ run: npm test }] }
  deploy: { runs-on: ubuntu-latest, needs: test, steps: [{ run: ./scripts/deploy.sh }] }

  report:
    runs-on: ubuntu-latest
    needs: [build, test, deploy]
    if: always()
    steps:
      - uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: >-
            ${{ contains(needs.*.result, 'failure') && 'failure'
             || contains(needs.*.result, 'cancelled') && 'cancelled'
             || 'success' }}
          message: 'build: ${{ needs.build.result }}, test: ${{ needs.test.result }}, deploy: ${{ needs.deploy.result }}'

The report action reads the callback URL and token from the workflow inputs, so it works from any job.

Update Jira fields instead of running a workflow

A jira_update action changes the work item directly, with the same permission check and audit comment. It can add and remove labels and set text, number and single-select fields.

{
  "id": "request-hotfix",
  "label": "Request a hotfix",
  "type": "jira_update",
  "form": [{ "name": "why", "label": "Why can't it wait?", "type": "textarea", "required": true }],
  "jira": {
    "addLabels": ["hotfix"],
    "removeLabels": ["next-release"],
    "setFields": { "customfield_10050": "{{input.why}}" }
  },
  "showWhen": { "issueTypes": ["Bug"], "labelsNone": ["hotfix"] },
  "allow": { "groups": ["developers", "support"] }
}

To find a field id like customfield_10050, open https://<your-site>.atlassian.net/rest/api/3/field in a browser where you're signed in to Jira. It lists every field with its id and name. Labels you add can trigger your existing Jira Automation rules; see Keep your label automations.

Use a workflow from another repository

github.repo overrides the repository mapped to the project, for example a shared ops repository with deploy workflows for every service.

{
  "id": "restart-service",
  "label": "Restart service",
  "style": "danger",
  "type": "github_workflow",
  "github": {
    "repo": "acme/ops",
    "workflow": "restart.yml",
    "ref": "main",
    "inputs": { "service": "shop", "issue_key": "{{issue.key}}" }
  },
  "allow": { "groups": ["sre"] }
}

The GitHub token needs access to that repository too.

Start a workflow you can't change

For a workflow you can't edit, like one owned by another team, set github.report: false. Cuelight won't send cuelight_callback_url and cuelight_token, so the workflow only needs its own inputs.

{
  "id": "nightly-now",
  "label": "Run nightly build now",
  "type": "github_workflow",
  "github": { "repo": "acme/platform", "workflow": "nightly.yml", "report": false }
}

The run can't hand back a message or next steps. The panel shows it as running and offers Refresh status, which asks GitHub once whether it finished.

Keep secrets out of run lines

Form values come from people. Don't write ${{ inputs.note }} inside a run: script, because a crafted value could run commands on your runner. Pass inputs through env: and quote them:

- name: Post the note
  env:
    NOTE: ${{ inputs.note }}
  run: ./scripts/notify.sh "$NOTE"