Jira

Draft bugs from run failures and send them to Jira Cloud after you confirm.

Astra Scout collects the failures of a run or an exploration, drafts a bug from the run's own data, and sends it to Jira Cloud after you confirm. Nothing is sent without your approval.

Admin: create the OAuth app (once)

Someone who can create Atlassian apps, usually a Jira admin, does this once for the company.

1. Open the Atlassian developer console, click Create → OAuth 2.0 integration and name it, for example Astra Scout.

2. Under Permissions, add the Jira API and configure these classic scopes: read:jira-work, write:jira-work and read:jira-user. Astra Scout requests offline_access itself.

3. Under Authorization, configure OAuth 2.0 (3LO) and enter this Callback URL exactly:

   http://127.0.0.1:47219/callback

   If the port is taken, set SCOUT_JIRA_CALLBACK_PORT=<port> and register http://127.0.0.1:<port>/callback instead.

4. Under Settings, copy the Client ID and Secret.

5. Under Distribution, turn Sharing on only if users belong to a different site than the account that created the app.

6. Give the Client ID and Secret to testers in one of these ways (never commit them):

   • At build time: SCOUT_JIRA_CLIENT_ID=… SCOUT_JIRA_CLIENT_SECRET=… ./scripts/build-stage.sh (or build-mac-app.sh --release). The values are embedded in the server binary, so use this only for internal releases.
   • At runtime: set the same variables for the Astra Scout process, for example with launchctl setenv. They win over build-time values.
   • In the app: Settings → Jira, in the Client ID and Client secret fields. The secret is stored encrypted and is not shown again.

Tester: connect

1. Open Settings → Jira and click Connect. Your browser opens Atlassian's consent page. Choose the site and Accept.
2. Back in Astra Scout, choose the Project, Issue type (default Bug), Default labels, components and Bug language (Tiếng Việt or English).

Disconnect removes all Jira secrets on the machine: the refresh token and the client secret entered in Settings. To revoke the app completely, visit https://id.atlassian.com/manage-profile/apps.

The access token lives only in the server's memory. The refresh token is stored encrypted with a key held in the macOS Keychain, readable only by the signed Astra Scout app. It rotates on each refresh and expires after 90 days without use, after which you click Connect again.

Send a bug

On a run that is Failed, Unsure or Passed with warnings, or on an exploration with issues, click Report Bug to Jira…, or choose Device → Report Bug to Jira… (Shift+Cmd+B). On a row of the Test Runs navigator, the context menu item Report Bug to Jira… does the same. The dialog lists one row per distinct problem:

Problem	Selected by default
The failing step that stopped the flow	Yes
A crash (merged with the failing step when the crash caused it)	Yes
A failing optional step	No
A failed (optional) or unsure *WithAI check	No
A tracking rule that failed or warned	Failed: yes. Warning: no.
Workspace run: each failing flow (identical failures are merged)	By kind
Exploration issue	Yes
Exploration warning	No

A blocked run or a run with a reason code is not suggested as an app bug.

Each row has an editable title and summary, the facts Astra Scout recorded (steps, expected and actual, device, OS, app id and version, Astra Scout version, crash), and attachments you can tick:

• A video clip around the failing step, and before and after screenshots (cut with ffmpeg if available).
• The crash report (.ips on iOS, a logcat excerpt on Android) and tracking results.
• The flow YAML and the run report.

You can ask the AI to rewrite the title and summary. If it adds facts that are not in the run, Astra Scout keeps your original text.

Click Send. Astra Scout shows a native dialog listing exactly what will be sent where. Each selected failure becomes a separate issue, issues from the same submission are linked "relates to", and the issue key is written into the run report.

Duplicates

Each problem gets a fingerprint label scout-fp-<12 hex>. Before sending, Astra Scout searches the project for an open issue with the same fingerprint. If one exists, the row offers Add a comment + attachments to KEY-12 instead of creating a new issue. New issues carry the fingerprint, astra-scout and your default labels.

Redaction

Everything sent passes through a redactor:

• Environment values, typed text (inputText, setClipboard) and anything named like password, secret, token or apikey become ***.
• Absolute paths become <workspace>/… or ~/…, and temp paths become <tmp>/….
• The attached YAML and report are the redacted versions.
• Secrets are matched in many encodings (JSON, HTML, percent-encoding, Unicode forms, case-insensitive, truncated fragments), and the redactor errs on the side of over-redacting.

Review before you send

Some things are not redacted by design: literal strings inside evalScript or runScript, on-screen text used in selectors, and absolute paths outside your home folder and workspace. Videos and screenshots can show typed text. For sensitive flows, untick the clip and screenshots, or leave auto-send off.

Priority from severity

With the Set Priority from the severity of exploration findings option in Settings → Jira you can set Priority from the severity of exploration findings. Severity 5 maps to the highest priority in the project's list and severity 1 to the lowest. If the list cannot be read, the project default is used.

Auto-send crashes

Auto-send crashes is off by default. It can only be turned on through a native dialog, and it turns itself off when Astra Scout restarts. When on, a run that crashes the app creates an issue with the video and crash log (redacted), but only when no duplicate exists and at most N per hour (default 3, maximum 20). If Astra Scout cannot tell whether a duplicate exists, it sends nothing.

From a terminal

The report_bug MCP tool lets an AI CLI prepare a draft, but the CLI never receives the Jira token and cannot send on its own. Astra Scout shows a native confirmation dialog, and the request is listed as Awaiting confirmation under Activity from CLIs in Settings → MCP. See The scout plugin.

Common problems

Symptom	Fix
"Port 47219 is busy"	Close the program using it, or set SCOUT_JIRA_CALLBACK_PORT and register the matching callback.
redirect_uri mismatch	The app's Callback URL must be exactly http://127.0.0.1:<port>/callback.
"Jira session expired or revoked"	The refresh token was revoked or is older than 90 days. Click Connect again.
You cannot see the project	The account lacks Browse project permission on that site.
Creating the issue fails on issuetype or components	Choose the issue type again or remove a component that does not exist in the project.
The video is not attached	It exceeds the site's attachment limit. Install ffmpeg to cut a shorter clip.

First real check

Try it with a test project first: run a failing flow, send the bug, run again (the row should offer a comment), then disconnect and confirm the secrets are gone.