GitHub setup

Cuelight starts workflows with a GitHub token that a Jira admin saves once. People who press the buttons don't need GitHub accounts.

Create a token

  1. In GitHub, open Settings → Developer settings → Personal access tokens → Fine-grained tokens and choose Generate new token.
  2. Set Resource owner to the organization or account that owns your repositories. An organization may need to approve the token.
  3. Pick an expiration that fits your policy. When the token expires, buttons show an error until an admin saves a new one.
  4. Under Repository access, choose Only select repositories and pick the ones Cuelight should run workflows in.
  5. Under Repository permissions, set:
PermissionAccessWhy
ActionsRead and writeStart workflows and check a run's status
ContentsReadRead workflow files for the Test button
MetadataReadRequired by GitHub for every token
  1. Generate the token and copy it.
  2. In Jira, open Settings → Apps → Cuelight → GitHub, paste it and choose Test connection.

Cuelight stores the token encrypted in Forge storage and never shows it again. Use Replace token to rotate it or Disconnect to remove it.

Prepare a workflow

A workflow can be started from Jira when:

  • it runs on workflow_dispatch,
  • the file is on the repository's default branch (GitHub only starts workflow_dispatch workflows that exist there, even if you run them on another ref),
  • it declares every input the action sends,
  • it declares cuelight_callback_url and cuelight_token, unless the action sets github.report: false.
name: Deploy
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:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Deploy
        env:
          ENVIRONMENT: ${{ inputs.environment }}
        run: ./scripts/deploy.sh "$ENVIRONMENT"
      - 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

if: always() makes the report step run when earlier steps fail, so the work item turns red instead of waiting. The Test button on the Actions tab checks all of the above and lists what's missing.

Which repository and ref

Each Jira project maps to one repository and a default ref under Cuelight settings → Projects. An action can override both with github.repo and github.ref. The ref can use templates, like {{issue.key}} for branches named after work items. If a templated ref comes out empty, the action doesn't start and says so.

If no report arrives

Cuelight doesn't poll GitHub. If a run hasn't reported within 30 minutes, the panel shows No report received with a Check status button that asks GitHub once for the run's result and finishes the run if GitHub has. For workflows that set github.report: false, the panel offers Refresh status instead, which does the same.