---
name: jira-evidence
description: "Upload screenshots to GitHub…"
---

# JIRA Evidence Posting

Upload captured screenshots and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes screenshots and comment templates already exist in the evidence directory.

## Arguments

`$ARGUMENTS`: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`

- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
- `EVIDENCE_DIR` (required): Directory containing screenshots and templates (e.g., `./evidence`)
- `PR_NUMBER` (required): GitHub PR number to update description

## Prerequisites

- `JIRA_API_TOKEN` environment variable set
- a jira-cli config — `.lisa/jira-cli/.config.yml` if the `setup-jira-cli`
  SessionStart hook wrote one, otherwise `~/.config/.jira/.config.yml`. `server`
  and `login` are read from whichever is used, and the fallback is announced on
  stderr rather than taken silently.
- `gh` CLI authenticated
- Evidence directory containing:
  - `NN-name-viewport.png` screenshots (numbered, e.g., `01-search-step-desktop.png`)
  - `comment.txt` — JIRA wiki markup (generated by `generate-templates.py`)
  - `comment.md` — GitHub markdown (generated by `generate-templates.py`)

## Usage

```bash
bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
```

### Example

```bash
bash .claude/skills/jira-evidence/scripts/post-evidence.sh PROJ-123 ./evidence 42
```

## What It Does

1. **Read JIRA config** — Resolves the jira-cli config (`$PROJECT_DIR/.lisa/jira-cli/.config.yml` first, then `~/.config/.jira/.config.yml`, announcing the fallback) and reads `server` and `login` from it dynamically — no hardcoded values. Exits 1 naming both paths when neither exists. The same resolved path is then passed to `jira issue move` as `--config`, so the CLI cannot end up on a different config than the one this script parsed.
2. **Upload to GitHub `pr-assets` release** — Uploads `NN-name-viewport.png` screenshots via `gh release upload --clobber`, creating CDN URLs that render in GitHub markdown
3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body using `gh pr edit`
4. **Upload JIRA attachments** — Uploads screenshots via REST API v3 so `!filename.png!` wiki markup renders inline
5. **Post JIRA comment** — Posts `comment.txt` as a new comment via REST API v2 (wiki markup with embedded images)
6. **Move ticket to the configured review status** — Resolves `jira.workflow.review` (or the `jira.workflow.code_review` alias) from `.lisa.config.json` / `.lisa.config.local.json` and transitions via `jira issue move`. `review` is optional; when unset, the ticket stays in `claimed` and this step is skipped. Never transition to a status not named in `config.jira.workflow`. If the configured status is not a valid transition from the current state, log a warning and skip.

## Screenshot Naming Convention

Only files matching `NN-*.png` (two-digit prefix) are uploaded. Other files in the evidence directory are ignored.

```text
evidence/
  01-search-step-desktop.png    ✓ uploaded
  02-confirm-step-desktop.png   ✓ uploaded
  03-search-step-mobile.png     ✓ uploaded
  comment.txt                   used for JIRA comment
  comment.md                    used for PR description
```

## Troubleshooting

### Images not rendering in GitHub PR

Images must be in the `pr-assets` GitHub release (not committed to git). The script handles this via `gh release upload`. If the release does not exist, create it first:

```bash
gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence screenshots"
```

### JIRA comment shows `!filename.png!` as text (not image)

The screenshot must be uploaded as a JIRA attachment before posting the comment. The script uploads attachments first then posts the comment — always in that order.

### JIRA API returns 403 on attachment upload

Ensure `JIRA_API_TOKEN` is set and `login` in the resolved jira-cli config (`.lisa/jira-cli/.config.yml`, else `~/.config/.jira/.config.yml`) matches your Atlassian account email.
