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-stagingOffering 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 finishedAsk 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.shRun 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"