Getting started

This guide takes about 15 minutes. You need to be a Jira admin, and you need a GitHub repository with a workflow you can change.

1. Install

Install Cuelight for Jira from the Atlassian Marketplace. Cuelight works with Jira Cloud. Install on Jira explains each screen and what the app asks permission for.

After installing, open Settings → Apps → Cuelight. The Setup tab shows a checklist that follows the steps below.

2. Connect GitHub

Create a fine-grained personal access token in GitHub with these repository permissions:

PermissionAccessWhy
ActionsRead and writeStart workflows and check their status
ContentsReadCheck that a workflow declares the inputs Cuelight sends
MetadataReadRequired by GitHub for every token

Paste it on the GitHub tab and choose Test connection. Cuelight shows how many repositories the token can reach. The token is stored encrypted and never shown again. See GitHub setup for step-by-step instructions.

3. Map a project to a repository

On the Projects tab, pick a Jira project and enter its repository as owner/repo, plus the default ref, usually main. Cuelight checks that the token can reach the repository before saving.

4. Add your first action

On the Actions tab, choose Add from template → Deploy to staging. This adds an action like this to the JSON editor:

{
  "id": "deploy-staging",
  "label": "Deploy to staging",
  "style": "primary",
  "type": "github_workflow",
  "github": {
    "workflow": "deploy.yml",
    "inputs": {
      "environment": "staging",
      "issue_key": "{{issue.key}}",
      "reason": "{{input.reason}}"
    }
  },
  "form": [{ "name": "reason", "label": "Reason", "type": "textarea", "maxLength": 300 }]
}

Change workflow to your workflow file, and add showWhen and allow if you want to limit where the button shows and who can press it (see Rules and permissions). Save. Cuelight validates the JSON and points at the exact field if something is wrong.

5. Prepare the workflow

The workflow must run on workflow_dispatch, live on the default branch, and declare every input the action sends, plus the two that Cuelight adds so the run can report back:

on:
  workflow_dispatch:
    inputs:
      environment: { type: string, 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 }

Choose Test next to the action. It reads the workflow file from GitHub and lists anything missing.

6. Press the button

Open a work item in the mapped project. The Next steps panel is in the right column, below the other fields. Press Deploy to staging, add a reason and run it.

The panel shows the run as running, and Cuelight adds a comment to the work item:

▶ Deploy to staging started by Ayşe Kaya. Inputs: environment=staging, issue_key=SHOP-1, reason="QA pass 2"

7. Hand back next steps

Add a report step at the end of the job. It runs even when earlier steps fail:

- name: Hand back the next step
  if: always()
  uses: huseyinbuyukdere/cuelight-report@v1
  with:
    status: ${{ job.status }}
    message: Deployed ${{ github.sha }} to ${{ inputs.environment }}
    next: rollback-staging, promote-production

When the workflow finishes, the panel turns green or red without a page reload, shows the message and offers Roll back staging and Promote to production. Those ids must be actions you've defined; availability: next-only keeps them hidden until a run offers them.

That's the loop. Next, follow one ticket from To Do to Done in the walkthrough, or pick up smaller pieces from Workflow patterns.