Connect Jira

1. 1

   Create one Jira space per product

   Keep each product's fixes in its own space, the same way each product is its own site in Sarcio. A team-managed software space with the Kanban template works well. Sarcio files tickets as a Bug by default, so check the space has that issue type (add it, or set Issue type to Task in step 3), and a Done status to move tickets to when the fix merges.

   Keep the space key short. It appears in every branch and PR title Sarcio creates, for example MERIDIAN-2 fix: … on branch sarcio/meridian-2-fix-2d3ad7e8.

2. 2

   Connect Jira to your workspace

   Open the Integrations tab and scroll to Jira. The Jira connection is a workspace connection: it belongs to the workspace, not to a person, and only admins can add, replace or remove it. Every ticket and comment Sarcio writes appears as the account behind it.

   Recommended: a service account or bot user's API token

   Give Sarcio an Atlassian identity of its own, so tickets and comments come from Sarcio rather than a teammate and keep working when people leave.

   • Create the account. Where your Atlassian plan offers them, create a service account for Sarcio in Atlassian Administration. Otherwise, create an ordinary Atlassian account used only by Sarcio, for example sarcio-bot@acme.com.
   • Give it only the spaces Sarcio uses. It needs Browse projects, Create issues, Add comments and Transition issues there. To @mention approvers it also needs the global Browse users and groups permission; without it, approvers are named instead.
   • Create its API token. For a bot user, sign in as it and create one under Security → API tokens. For a service account, an organization admin creates the token on the service account's page, choosing Jira and the scopes read:jira-work, write:jira-work and read:jira-user (the last one lets Sarcio read who the token is and @mention approvers; without it the connection shows Owner unknown and approvers are named instead). Service account tokens expire in at most a year; note the date.
   • Save it in Sarcio. Under Add a service account token (recommended), enter your site as the host (acme.atlassian.net), the account's email (a service account's ends in @serviceaccount.atlassian.com), the token, and the token's expiry date, then press Save token.

   When you save, Sarcio asks Jira who the token belongs to (GET /rest/api/3/myself, an identity read that needs no extra permission). A service account or app shows Bot token. A person's account shows Personal with a banner; for a bot user that is expected, since Atlassian treats it as an ordinary account. If Jira accepts the token nowhere, it still saves, badged Owner unknown with a warning.

   Service account tokens and the api.atlassian.com gateway

   Atlassian requires service account (scoped) API tokens to call Jira through its platform gateway, https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3, and refuses them on your site's own address. Sarcio handles this for you: on save it tries your site address and the gateway (the gateway first for a @serviceaccount.atlassian.com email), looks up your site's cloud id from https://<site>.atlassian.net/_edge/tenant_info, and keeps whichever address accepts the token. The saved confirmation then says through the api.atlassian.com gateway. Browse links in tickets still point at your site. Classic API tokens keep using your site address.

   What Sarcio checks, and what the warnings mean

   Beyond the owner, Sarcio checks what the account can do. Warnings show on the connection under Workspace connections and never stop the save:

   • Can't browse users. The account lacks the global Browse users and groups permission, so go-live comments name approvers instead of @mentioning them.
   • Can't see project KEY. A site files tickets into a space the account can't browse. Add the account to that space.
   • Jira didn't accept this email and token. Neither your site address nor the gateway accepted them: check the email, and that the token hasn't expired or been revoked.

   After changing a permission in Jira, press Re-check on the connection to run the checks on the stored token again. Jira doesn't report when an API token expires, so enter the date on the token form: workspace admins then get an email 14 and 3 days before it, once per threshold, and the connection shows an expiry chip.

   Quick start: connect Jira with your account

   Trying Sarcio out? Under Quick start: connect Jira with your account, press Connect Jira. On Atlassian's consent screen, pick your site under Install app on. Access is restricted to that one site. Sarcio asks to view and update Jira work items (read:jira-work, write:jira-work) and nothing else. Press Accept. If your Atlassian account has already granted Sarcio another site, type the one to connect in Jira site before pressing Connect Jira: Sarcio won't guess between them.

   It is quick, but it connects the workspace as you:

   • Tickets and comments appear as you.
   • It reaches every space your Atlassian account can on that site.
   • The connection stops working if you leave or lose access.
   • The connection wears the Personal badge, with a warning banner on the Integrations tab.
3. 3

   Set each site's ticket conventions

   The credential says which Jira to talk to. Each site then says which space its tickets go in and how PRs are named. Ticketing stays off for a site until it has both. On the Sites tab, press Manage next to the site, open Ticketing, fill in the settings below and press Save ticketing. Remove ticketing turns it off for that site again.

   Setting	What it does
   Jira site	One of your Jira connections, e.g. acme.atlassian.net. The form is disabled until the workspace has one.
   Project key	The space fix tickets file under, e.g. SHOP.
   Issue type	Issue type by name. Blank files Bugs; set it (e.g. Task) for a space without a Bug type.
   File the ticket	On approval (default) files the ticket when a reviewer approves and the patch goes live. On draft files it as soon as a draft exists.
   Commit template	The title and commit message convention, with {ticket} and {summary} placeholders. It must contain {summary}; {ticket} {summary} works well.
   Transition on merge	The transition applied when the patch retires because its PR merged, e.g. Done. Leave it blank to keep the ticket where it is.
   Epic	Optional. A parent epic every fix ticket files under.
   Labels	Optional. Comma-separated labels added to every fix ticket.

   The {ticket} {summary} template is what makes the rest of this guide work: the PR title starts with the issue key, and the branch name contains it.

4. 4

   See what lands in Jira

   Sarcio files the ticket itself. The summary starts with [Sarcio], and the description carries the report, where it was reported, the fix, the patch id and when the live patch expires.

   

   Enlarge

   In Sarcio	In Jira
   Patch drafted (File the ticket: On draft)	Fix ticket created
   Patch approved and live	Ticket created if missing, plus a comment with the fix, the approvers (as @mentions where Jira can match them) and the expiry
   Pull request opened	Comment with the PR link
   Patch expiring soon	Warning comment, with the PR link when there is one
   Pull request merged, patch retired	Comment, and your Transition on merge (e.g. Done)
   Patch retired another way	Comment noting it retired without a merged fix

   How approvers are @mentioned

   The go-live comment says who approved the patch, for example Approved in Sarcio by @Ada Lovelace and Bo K. · low risk. An approver who linked their Atlassian account is mentioned by that account, with no lookup. For every other approver, Sarcio looks up a Jira account by their Sarcio email (GET /rest/api/3/user/search) and, when exactly one active person matches, writes a real mention, so Jira notifies them and shows their current name. When nobody matches, the match is ambiguous, or the account can't browse users, the approver is named the way the pull request names them (Bo K.). The email is only the lookup key and is never written into the comment. Matches are cached for a day, misses for an hour.

   Jira matches an email even when the person's profile hides it, so a hidden email still resolves when it is the only match. The report page links the ticket next to the pull request, so a reviewer can jump either way.

   Get @mentioned: link your Jira account

   When the email lookup can't find someone, they can link their own account: open Account, press Link Jira, then Accept. Atlassian asks only to View me (read:me), and Sarcio stores no token. One link covers every Jira Cloud site. If an admin turns on acting links, you can also let Sarcio act as you. What a link can and cannot do.

   

   Enlarge

   

   Enlarge

   Want summaries, descriptions and comments in your team's style? Add a Jira writing instruction, such as Write summaries as user-facing problem statements under 80 characters; include acceptance criteria as a checklist. Sarcio still appends the patch id, report link and expiry. See Customize PR, commit and ticket text.

   Ticketing is best-effort. If Jira is down or a setting is wrong, the patch action still succeeds and the ticket is simply missing.

5. 5

   Show Sarcio's pull requests on the ticket

   Jira's Development panel lists branches, commits and pull requests whose name or title contains the issue key. Sarcio's branch and title naming guarantee that, so all you need is Jira's connection to your forge. Set it up once per forge.

   

   Enlarge

   GitHub: GitHub for Atlassian

   • In Jira, go to Apps → Explore apps, find GitHub for Atlassian (by Atlassian, free; formerly GitHub for Jira) and press Get it now.
   • Open the app's Configure page, choose GitHub Cloud, and authorize the Atlassian app on GitHub.
   • Pick your organization (use Select another organization if it isn't listed). On GitHub's install screen choose Only select repositories, pick the repositories your sites use, and install.
   • GitHub may ask you to Confirm access with 2FA. Only the signed-in account's owner can pass it, so do this step yourself.
   • Back in Jira the organization shows as connected, and existing history starts to backfill.

   Choose "Only select repositories"

   The install screen lists organization-wide permissions (read members and administration; read and write code, issues and pull requests on the selected repositories). That's standard for the app. Choosing All repositories would also expose private repositories that have nothing to do with Sarcio.

   GitLab: GitLab for Jira Cloud

   • In Jira, go to Apps → Explore apps, find GitLab for Jira Cloud (by GitLab, free) and press Get it now.
   • Open Apps → Manage apps → GitLab for Jira Cloud → Get started, then Sign in to GitLab and approve on gitlab.com.
   • Press Link groups, choose the group that holds your project, and wait for "Group successfully linked".

   

   Enlarge

   Check the group path, not the name

   The link dialog shows each group's display name. Two groups can share a display name while having different paths (for example acme-group and acme-group1). Confirm the path in GitLab before linking.

   Bitbucket: built into Jira

   Bitbucket Cloud needs no Marketplace app, but it takes two approvals, one on each side.

   • In Jira, open Jira admin settings → Integrations → DVCS accounts and press Link Bitbucket Cloud workspace. Bitbucket shows Jira requests access: pick your workspace under Authorize for workspace and press Grant access.
   • Back on DVCS accounts, the workspace is marked INCOMPLETE with Bitbucket account is requesting access to Jira. Press Grant access there too. Until you do, no Bitbucket branches or pull requests reach tickets.

   

   Enlarge

   Once granted, the workspace lists its repositories with Smart Commits ticked. Every repository in the Bitbucket workspace is linked; untick Smart Commits on any you don't want moving tickets. Existing branches and pull requests backfill over a few minutes, so a ticket's panel can stay empty right after linking.

   

   Enlarge

Troubleshooting

• No ticket appears. Check the site has ticketing settings (step 3) whose Jira site matches a saved connection. With File the ticket: On approval, nothing is filed until a reviewer approves.
• Tickets fail to file. The Issue type must exist in the space by that exact name, and the account behind the credential needs permission to create issues there. An API token that was revoked, or an OAuth connection removed in your Atlassian account, fails the same way; connect again.
• The ticket never moves to Done. Transition on merge must match a transition name in the space's workflow, and it only runs when the PR merges.
• PRs don't show on the ticket. Make sure the PR title starts with the key (Commit template), the repository is one you selected or linked in the Development panel app, and for Bitbucket that both Grant access steps are done.
• After connecting you land on another dashboard address. Older deployments return from the provider to a shared dashboard address instead of your workspace. The connection is saved either way: go back to your workspace address (e.g. acme.sarcio.io) and it's listed there.

What crosses into Jira, and the exact scopes: Issue tracking permissions. Captured console, network and screenshot data never crosses into Jira.