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:
| Person | Jira group | What they do |
|---|---|---|
| Elif Demir | developers | Writes the fix, runs tests, deploys previews |
| Ayşe Kaya | qa-team | Tests on staging and signs it off |
| Deniz Arslan | release-managers | Decides 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.
| Status | Button | Elif (dev) | Ayşe (QA) | Deniz (release) |
|---|---|---|---|---|
| To Do | Create branch | ✓ | disabled | disabled |
| In Progress | Deploy preview | ✓ | disabled | disabled |
| In Progress | Run tests | ✓ | ✓ | disabled |
| In Review | Run tests | ✓ | ✓ | disabled |
| In Review | Deploy to staging | ✓ | ✓ | disabled |
| In Review | Mark QA passed | disabled | ✓ | disabled |
| Ready for Release | Promote to production | disabled | disabled | ✓ |
| Done | Roll back production | disabled | disabled | ✓ |
Four more buttons never show from rules. A run offers them when they make sense:
| Offered after | Button | Who can press it |
|---|---|---|
| Run tests fails | Re-run tests | Developers, QA |
| Deploy to staging succeeds | Roll back staging | Everyone above |
| Promote to production succeeds | Check production | QA, release managers |
| Check production fails | Roll back production | Release 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 deploysmain.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-productionis 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 readytests.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-testsdeploy.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 releasesmoke.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-productionCheck it before you rely on it
- 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.
- 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.
- 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.