Jira

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

Testers report bugs to Jira Cloud from Astra Scout, and a Jira admin sets up the connection.

Astra Scout collects the failures of a run or an exploration, drafts a bug from the run's own data (steps, video, crash), and sends it to Jira after the user confirms. Nothing is sent without approval.

Setup has three parts, done by different people:

1. An admin registers an OAuth app on Atlassian for the company, so Astra Scout can sign in to Jira on a user's behalf. The admin gives its Client ID and secret to the testers.
2. Each tester connects Astra Scout to their Jira account.
3. Each project chooses where its bugs go (Jira site, project, issue type).

Admin: create the OAuth app

Someone who can create Atlassian apps, usually a Jira admin, creates one OAuth app 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

   The same URL is shown, with a copy button, on the OAuth App page of Astra Scout (see below). If port 47219 is taken, see Technical details.

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 over a safe channel. Do not commit them. The simplest way is to enter them in the app, as the steps below show. Two other ways (at build time, at runtime) are in Technical details.

To enter the Client ID and secret in the app:

1. Choose Astra Scout > Settings… (Cmd+,) and click Jira in the sidebar.
2. Under Account, click the OAuth App row. The row is hidden when both values already come from the environment.
3. The OAuth App page shows the Callback URL with a copy button. Register this URL in the Atlassian console (step 3 above).
4. Paste the Client ID into its field. It is saved when you press Return or click another field.
5. Paste the Client secret and click Save. The note "Client secret saved" appears. The secret is stored encrypted and is not shown again. The field then reads "saved", with where it is kept.
6. Open Admin Guide opens this page.

Tester: connect

1. Choose Astra Scout > Settings… (Cmd+,) and click Jira in the sidebar.
2. Under Account, the Jira Cloud row says "Not signed in". If it adds "Connect needs an OAuth app", the admin has not set it up yet: ask them.
3. Click Connect. The browser opens Atlassian's consent page, and the row reads "Waiting for sign-in in the browser…" (click Cancel to give up). Choose the site and Accept.
4. Back in Astra Scout, the row shows the account name and Disconnect. A Project Settings… button appears below it.

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 sign-in expires after 90 days without use. Then click Connect again. How tokens are stored is in Technical details.

Choose where the bugs go

This step picks the Jira project that receives the bugs. The choice is saved in the workspace, so everyone who opens the project reports to the same Jira project. Open a workspace first.

1. Choose File > Project Settings… (Option+Cmd+,), or click Project Settings… in Settings > Jira. If the window says "Jira is not connected.", click Connect Jira in Settings… and connect first.
2. In Report Destination, set:
   • Site: shown only when the account has more than one Jira site. Choose it first; Project stays disabled until you do. With one site, it is chosen together with the project.
   • Project: pick from the list (key and name).
   • Issue type: appears once a project is chosen. It starts as Bug (or the project's first type if it has no Bug).
   • Default labels: comma-separated. Spaces inside a label become hyphens. Saved when you press Return or leave the field.
   • Components: ticks for the project's components. Shown only when the project has some. Choosing another project clears them.
   • Bug language: Tiếng Việt (the default) or English. This is the language of the drafted bug text.
   • Set Priority from finding severity: see Priority from severity.
3. Changes apply at once and are saved in the workspace.

Send a bug

A bug can come from a failed or unsure run, a run with warnings, or an exploration with issues. A run that is Passed with a reason that mentions warnings counts as a run with warnings. A Blocked or Incomplete run, or any run that carries a reason code (device, driver, AI, limit, approval), is not an app bug and is not offered.

1. Open the report sheet in one of these ways:

   • In the runner or the Test Runs navigator, right-click the run's row and choose Report Bug to Jira…. The row's detail has the same button.
   • Choose Device > Report Bug to Jira… (Shift+Cmd+B). It reports the exploration that found issues if there is one, else the newest run with something to report. The item is disabled when there is nothing to report.
   • In the Explore app window, click Report Bug to Jira… in the results header (it reports all issues), or select an issue in the Issues tab and click Report Bug to Jira… in the inspector (one issue).
   • On a failed assertEvents line in the editor, open the inspector and click Report Bug to Jira… in the Fix section. It reports that step.

   

2. The Report to Jira sheet opens and shows "Collecting bugs, cutting videos and looking for duplicates…". It lists one row per distinct problem. If Jira is not set up, it says "Jira isn't set up" and offers Open Project Settings….

   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 row shows its kind (for example Failed step, Crash, AI check, Tracking, Exploration), its severity, and badges such as "severity 4/5" (explorations), "crash caused a step failure", "AI rewrote" and "Also seen in: …" (the same problem in other flows).

3. Tick or untick the checkbox of each row to choose what is sent. Click the chevron at the end of a row (Expand) to open it.

4. In an open row, edit the title and the summary. Under them are the fingerprint (a short code that identifies the same problem) and Facts recorded by Astra Scout (not editable): steps, expected and actual, device, OS, app id and version, crash. Under Attachments, tick the files to send:

   • 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.

5. Optionally type a line in Extra note; it is added to every issue. The line under it ("N bugs selected") counts the ticked rows.

6. Optionally click Rewrite Title and Summary with AI. It rewrites only the ticked rows. If the AI adds facts that are not in the run, Astra Scout keeps the original text. A row it rewrote shows "AI rewrote".

   

7. Click Send. Astra Scout shows a native dialog titled "Send to Jira?" that lists exactly what will be sent where. Click Send to Jira to go on, or Cancel.

8. The sheet then lists a result per row: Created or Commented, with the issue key as a link, or an error. Each ticked problem becomes a separate issue, issues from the same submission are linked "relates to", and the issue key is written into the run report. When the run is on the team cloud, the issue description links to it and the run is tagged with the issue key: see Team runs. Click Done.

Duplicates

Each problem gets a fingerprint label scout-fp-<12 hex> that identifies the same problem. While it prepares the sheet, Astra Scout searches the project for an open issue with the same fingerprint. If one exists, the row says "An open issue with the same fingerprint exists" with its key, and offers two choices:

• Add a comment + attachments to KEY-12 (selected by default), or
• Create a new issue.

New issues carry the fingerprint, astra-scout and the default labels.

Redaction

Redaction hides sensitive data before sending. 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.
• The redactor errs on the side of over-redacting rather than missing something.

Review before you send

The redactor masks known secret values and secret-looking keys. It does not mask: literal strings inside evalScript or runScript, on-screen text used in selectors, and absolute paths outside the 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 Set Priority from finding severity turned on in Report Destination, the Priority of an issue comes from the severity of the exploration finding. 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

When a run crashes the app, Astra Scout can create the issue by itself, with the video and the crash log (redacted).

1. Open File > Project Settings…. The Crashes section shows once Jira is connected and a project is chosen.
2. Set Max issues per hour first (1 to 20, default 3). The stepper is disabled while auto-send is on.
3. Turn on Auto-send crashes. A native dialog titled "Send crashes to Jira automatically?" names the site, the project and the limit. Click Turn on.
4. While it is on, a line shows "Sent N issues in the last hour."

It is off by default and turns itself off when Astra Scout restarts. It can be turned off at any time without a dialog. It sends only when no duplicate exists, and at most N per hour. If Astra Scout cannot tell whether a duplicate exists, it sends nothing: the draft waits for the user.

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 > Intelligence > MCP Connection. 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.
"The Jira session has expired or was revoked"	The refresh token was revoked or is older than 90 days. Click Connect again.
Project is disabled	The account has several Jira sites and none is chosen. Choose Site first.
You cannot see the project	The account probably lacks Browse project permission on that site.
Creating the issue fails on issuetype or components	Choose the issue type again or untick 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.

Try it on a test project

Run a failing flow, send the bug, run again (the row should offer a comment), then disconnect and confirm the secrets are gone.

Technical details

• Callback port: if port 47219 is taken, set SCOUT_JIRA_CALLBACK_PORT=<port> and register http://127.0.0.1:<port>/callback in the Atlassian console instead.
• Giving the Client ID and Secret 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.
• Giving the Client ID and Secret at runtime: set the same variables for the Astra Scout process, for example with launchctl setenv. They win over build-time values.
• Tokens: the access token lives only in the server's memory and is never sent to the UI or to a CLI. The refresh token is kept as the line under Account says: in a file encrypted with the app's own Keychain key, in the macOS Keychain, or in a private file on this Mac. It rotates on each refresh and expires after 90 days without use.
• The report destination is saved in .scout/project.json of the workspace.
• Redaction matches secrets in many encodings (JSON, HTML, percent-encoding, Unicode forms, case-insensitive, truncated fragments).