Walkthrough: one ticket, start to finish

This page builds the flow from the demo for real. One bug moves from To Do to Done. At every status, the right buttons show up for the right people, and each run hands back what comes next.

Copy the actions and workflows below, change the names to yours, and you have a working setup.

The team and the ticket

Three Jira groups, one project:

PersonJira groupWhat they do
Elif DemirdevelopersWrites the fix, runs tests, deploys previews
Ayşe Kayaqa-teamTests on staging and signs it off
Deniz Arslanrelease-managersDecides when it goes to production and rolls back

The ticket is SHOP-142: Checkout fails when a saved card is used. The project SHOP is mapped to the repository acme/shop with the default ref main.

The workflow has five statuses: To Do → In Progress → In Review → Ready for Release → Done. People move the ticket between them in Jira as usual. Cuelight never changes a status; it only shows buttons that fit the status the ticket is in.

What each person sees

Every button shows to everyone at its status. People outside the allowed groups see it disabled, with the reason underneath.

StatusButtonElif (dev)Ayşe (QA)Deniz (release)
To DoCreate branch✓disableddisabled
In ProgressDeploy preview✓disableddisabled
In ProgressRun tests✓✓disabled
In ReviewRun tests✓✓disabled
In ReviewDeploy to staging✓✓disabled
In ReviewMark QA passeddisabled✓disabled
Ready for ReleasePromote to productiondisableddisabled✓
DoneRoll back productiondisableddisabled✓

Four more buttons never show from rules. A run offers them when they make sense:

Offered afterButtonWho can press it
Run tests failsRe-run testsDevelopers, QA
Deploy to staging succeedsRoll back stagingEveryone above
Promote to production succeedsCheck productionQA, release managers
Check production failsRoll back productionRelease managers

The story

To Do. Elif opens SHOP-142 and presses Create branch. A workflow creates the branch SHOP-142 from main. The ticket gets two comments:

▶ Create branch started by Elif Demir. Inputs: issue_key=SHOP-142

✓ Create branch succeeded in 12s.

She moves the ticket to In Progress and pushes her fix to the branch.

In Progress. The panel now shows Deploy preview and Run tests. Elif presses Run tests. Two tests fail. The panel turns red with the message "2 tests failed" and offers Re-run tests. She fixes them, presses Re-run tests, and the panel turns green.

In Review. Elif moves the ticket to In Review. Ayşe, in QA, sees Run tests, Deploy to staging and Mark QA passed. She presses Deploy to staging and types a reason, "QA pass 1". When the deploy finishes, the panel offers Roll back staging with "Suggested by deploy.yml".

She tests on staging, then presses Mark QA passed. Cuelight adds the label qa-passed and the button disappears, since it only shows while that label is missing:

✓ Mark QA passed by Ayşe Kaya. Changes: labels="+qa-passed"

Ready for Release. Ayşe moves the ticket on. Only Deniz can press Promote to production. It asks for a reason and a confirmation first. The run succeeds and offers Check production.

Done. Deniz moves the ticket to Done. Roll back production stays available to release managers, in case something shows up later. If Check production had failed, the same button would have been offered straight away.

Everything that happened is on the ticket as comments, and on the Runs tab in Cuelight settings.

The actions

Paste this into Cuelight settings → Actions. Change the group names to your Jira groups and the status names to your workflow's. Status names aren't case-sensitive.

[
  {
    "id": "create-branch",
    "label": "Create branch",
    "description": "Creates a branch named after this work item from main.",
    "type": "github_workflow",
    "github": { "workflow": "create-branch.yml", "inputs": { "issue_key": "{{issue.key}}" } },
    "showWhen": { "statuses": ["To Do"] },
    "allow": { "groups": ["developers"] }
  },
  {
    "id": "deploy-preview",
    "label": "Deploy preview",
    "type": "github_workflow",
    "github": {
      "workflow": "deploy.yml",
      "ref": "{{issue.key}}",
      "inputs": { "environment": "preview", "issue_key": "{{issue.key}}" }
    },
    "showWhen": { "statuses": ["In Progress"] },
    "allow": { "groups": ["developers"] }
  },
  {
    "id": "run-tests",
    "label": "Run tests",
    "type": "github_workflow",
    "github": {
      "workflow": "tests.yml",
      "ref": "{{issue.key}}",
      "inputs": { "issue_key": "{{issue.key}}" }
    },
    "showWhen": { "statuses": ["In Progress", "In Review"] },
    "allow": { "groups": ["developers", "qa-team"] }
  },
  {
    "id": "rerun-tests",
    "label": "Re-run tests",
    "type": "github_workflow",
    "availability": "next-only",
    "github": {
      "workflow": "tests.yml",
      "ref": "{{issue.key}}",
      "inputs": { "issue_key": "{{issue.key}}" }
    },
    "allow": { "groups": ["developers", "qa-team"] }
  },
  {
    "id": "deploy-staging",
    "label": "Deploy to staging",
    "style": "primary",
    "type": "github_workflow",
    "github": {
      "workflow": "deploy.yml",
      "ref": "{{issue.key}}",
      "inputs": {
        "environment": "staging",
        "issue_key": "{{issue.key}}",
        "reason": "{{input.reason}}"
      }
    },
    "form": [{ "name": "reason", "label": "Reason", "type": "textarea", "maxLength": 300 }],
    "showWhen": { "statuses": ["In Review"] },
    "allow": { "groups": ["developers", "qa-team"] }
  },
  {
    "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", "qa-team", "release-managers"] }
  },
  {
    "id": "mark-qa-passed",
    "label": "Mark QA passed",
    "type": "jira_update",
    "jira": { "addLabels": ["qa-passed"] },
    "showWhen": { "statuses": ["In Review"], "labelsNone": ["qa-passed"] },
    "allow": { "groups": ["qa-team"] }
  },
  {
    "id": "promote-production",
    "label": "Promote to production",
    "style": "primary",
    "confirm": true,
    "type": "github_workflow",
    "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 }
    ],
    "showWhen": { "statuses": ["Ready for Release"], "labelsAny": ["qa-passed"] },
    "allow": { "groups": ["release-managers"] }
  },
  {
    "id": "smoke-production",
    "label": "Check production",
    "type": "github_workflow",
    "availability": "next-only",
    "github": { "workflow": "smoke.yml", "inputs": { "issue_key": "{{issue.key}}" } },
    "allow": { "groups": ["qa-team", "release-managers"] }
  },
  {
    "id": "rollback-production",
    "label": "Roll back production",
    "style": "danger",
    "type": "github_workflow",
    "github": {
      "workflow": "rollback.yml",
      "inputs": { "environment": "production", "issue_key": "{{issue.key}}" }
    },
    "showWhen": { "statuses": ["Done"] },
    "allow": { "groups": ["release-managers"] }
  }
]

A few choices worth noticing:

  • ref: "{{issue.key}}" runs tests and previews on the work item's branch. Staging gets it too, so QA tests the fix before it's merged. Production always deploys main.
  • labelsAny: ["qa-passed"] on Promote to production means release managers can't promote something QA hasn't signed off, even if someone moves the ticket too early.
  • rollback-production is a rule on Done and a step that Check production can offer. It's the same action. A next step and a rule never show the same button twice.
  • style: "danger" always asks for confirmation, so rollbacks can't happen by accident.

The workflows

Put these in .github/workflows/ on your default branch. Each one declares the inputs its actions send, plus cuelight_callback_url and cuelight_token so the run can report back.

create-branch.yml

name: Create branch
on:
  workflow_dispatch:
    inputs:
      issue_key: { type: string, required: true }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

permissions:
  contents: write

jobs:
  branch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Create the branch
        env:
          BRANCH: ${{ inputs.issue_key }}
        run: |
          git switch -c "$BRANCH"
          git push origin "$BRANCH"
      - name: Report
        if: always()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: ${{ job.status }}
          message: Branch ${{ inputs.issue_key }} is ready

tests.yml

Passing tests hand back nothing: the rule buttons are enough. Failing tests offer Re-run tests.

name: Tests
on:
  workflow_dispatch:
    inputs:
      issue_key: { type: string, required: true }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npm test

      - name: Report success
        if: success()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: success
          message: All tests passed

      - name: Report failure
        if: failure()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: failure
          message: Tests failed. Open the run to see which ones.
          next: rerun-tests

deploy.yml

One workflow for preview, staging and production. The next step depends on where it deployed.

name: Deploy
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [preview, staging, production]
        required: true
      issue_key: { type: string, required: true }
      reason: { type: string, required: false }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

concurrency: deploy-${{ inputs.environment }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v7

      - name: Tell Jira it's deploying
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: running
          message: Deploying ${{ github.ref_name }} to ${{ inputs.environment }}

      - name: Deploy
        env:
          ENVIRONMENT: ${{ inputs.environment }}
          REASON: ${{ inputs.reason }}
        run: ./scripts/deploy.sh "$ENVIRONMENT"

      - name: Report success
        if: success()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: success
          message: Deployed ${{ github.sha }} to ${{ inputs.environment }}
          next: >-
            ${{ inputs.environment == 'staging' && 'rollback-staging'
             || inputs.environment == 'production' && 'smoke-production'
             || '' }}

      - name: Report failure
        if: failure() || cancelled()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: ${{ job.status }}
          message: Deploy to ${{ inputs.environment }} didn't finish. Nothing was changed.

environment: on the job lets you use GitHub's environment secrets, and required reviewers if you want a second approval in GitHub. No step runs until that approval, so the panel just shows the run as running. If nobody approves within 30 minutes, it shows No report received, and Check status asks GitHub where the run is.

rollback.yml

name: Roll back
on:
  workflow_dispatch:
    inputs:
      environment: { type: string, required: true }
      issue_key: { type: string, required: true }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v7
      - name: Roll back
        env:
          ENVIRONMENT: ${{ inputs.environment }}
        run: ./scripts/rollback.sh "$ENVIRONMENT"
      - name: Report
        if: always()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: ${{ job.status }}
          message: Rolled ${{ inputs.environment }} back to the previous release

smoke.yml

name: Check production
on:
  workflow_dispatch:
    inputs:
      issue_key: { type: string, required: true }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: ./scripts/smoke.sh https://shop.example.com

      - name: Report success
        if: success()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: success
          message: Checkout, login and search work in production

      - name: Report failure
        if: failure()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: failure
          message: Production checks failed. Consider rolling back.
          next: rollback-production

Check it before you rely on it

  1. On the Actions tab, press Test next to each action. It reads the workflow from GitHub and lists any input the workflow doesn't declare.
  2. Make a test ticket and walk it through every status with someone from each group, or ask a Jira admin to add you to each group for an afternoon.
  3. Make a run fail on purpose, for example with a failing test, and check that Re-run tests shows up.

For smaller building blocks, see Workflow patterns. For every field, see Actions.