Connect once, route per project
The credential is entered once for the account. Each project then attaches to it, optionally pointing at a different repo, team, or Jira project.
Most reports that survive triage become work. The issue-tracker integration closes the gap between “feedback captured” and “work scheduled”: connect GitHub Issues, Linear, or Jira once, route it to the projects that need it, and from any report a triager can open a real tracker issue in one action. The report keeps a live back-link, and once you point your tracker’s webhook at uMarker, closing the issue moves the report too.
Connect once, route per project
The credential is entered once for the account. Each project then attaches to it, optionally pointing at a different repo, team, or Jira project.
Create in one click
From a report, Create ticket maps the title, description, a signed screenshot link, and (on GitHub) labels into a new tracker issue.
Status comes back
A webhook from the tracker moves the uMarker report when the issue does: done → resolved, reopened → in progress, and — on GitHub and Linear — cancelled → archived.
Idempotent, fails clean
A report already linked is never linked twice. If the tracker rejects the request, nothing partial is stored, and the report says so in plain words. The tracker’s own reason is kept on the connection.
Open the account’s Integrations page, pick the provider, and follow the guided steps. There are two ways in, and the panel shows only the ones that work on your platform:
Either way, the destination (project and issue type, repository, or team) is picked from a list fetched with your sign-in, never typed. uMarker validates the choice, stores the credential encrypted, and marks the connection active.
When your platform’s operator has set up the provider’s sign-in (see For operators), the card shows Connect with Jira, Connect with GitHub or Connect with Linear:
Press Connect with …. The window goes to the provider’s sign-in page.
Sign in and approve access. You come back to the panel, which reads Signed in with …. Choose where tickets go.
Choose the destination from the lists:
Press Test connection, then Connect.
If you’d rather not sign in, Use an API token instead switches to the token path below. When the provider isn’t set up on your platform, the button simply isn’t there and the token path is the only one.
uMarker authenticates with a token or API key you supply (a personal access token, a Linear API key, or a Jira API token). Pick your provider for what’s asked and where to get the credential:
| Field | Value |
|---|---|
| Credential | A personal access token (classic or fine-grained) with permission to create issues in the target repository. Sent as a bearer token. |
Repository (repo) |
Picked from the list of repositories the token can reach (searchable), e.g. acme/webapp. |
Issues are created via POST https://api.github.com/repos/{owner}/{name}/issues (GitHub REST API version 2022-11-28). The returned issue is keyed as #<number> and linked by its html_url.
GitHub is the one provider that also carries the report’s labels onto the issue (see What maps onto the issue).
| Field | Value |
|---|---|
| Credential | A Linear API key. Sent in the Authorization header as-is (no Bearer prefix). |
Team (team_id) |
Picked from the list of teams the key can see. |
Issues are created through Linear’s GraphQL API (https://api.linear.app/graphql) using the issueCreate mutation with the report’s title and description. The returned issue is keyed by its Linear identifier (e.g. ENG-142) and linked by its url.
| Field | Value |
|---|---|
| Credential | A Jira API token. Used with the email for HTTP Basic auth. |
Email (email) |
The Atlassian account email the token belongs to. Prefilled with your uMarker email; change it only if the token belongs to another Atlassian account. |
Jira site (base_url) |
Atlassian tokens don’t say which site they belong to, so this is the one thing you type. acme is enough; acme.atlassian.net or the full address work too, and the panel shows the address it will sign in to. |
Project (project_key) |
Press Find my projects, then pick from the list of projects the token can see. |
Issue type (issue_type) |
Optional, picked from that project’s issue types. Defaults to Task if left blank. |
Issues are created via POST {base_url}/rest/api/3/issue with the summary, issue type, and an Atlassian Document Format description. The returned issue is keyed by its Jira key (e.g. MD-45) and linked as {base_url}/browse/{key}. A one-click Jira connection calls the same API through https://api.atlassian.com/ex/jira/{cloudId} with the sign-in token instead.
The panel walks you through it, the same for each provider. Each step that needs the other service has a direct link to the exact page:
On the account’s Integrations page, press Connect on the tracker’s card. The panel opens on How to connect.
Follow the steps for your provider:
acme is enough. Press Find my projects and pick the project and, optionally, the issue type.Press Test connection. uMarker runs a real sign-in check against the tracker with exactly what is on screen (the same check as below), and saves nothing. A pass reads Signed in as, followed by what it reached: your Jira site, the repository, or Linear.
Press Connect. It turns on once the test passes; change a field after the test and the panel asks you to test again. Save without a passing test is there if you need it. The connection is stored active, with the credential encrypted at rest.
If the test fails, the panel says why in your language: the cause, a What to do: line (for example, that the token was refused and needs replacing, or that the repository or project wasn’t found), and the tracker’s own text folded under Details from the service, with the token scrubbed out of it.
A connection on its own files nothing. Attach it to the projects that should use it:
Open the project and go to its Distribution tab.
Attach the tracker connection.
Optionally set a target: a different repo, Linear team, or Jira project key and issue type than the connection’s default. Only the destination is overridable; the credential and base URL stay on the connection. A route is “where in your tracker”, never “whose tracker”.
Optionally turn on auto-create, so a new report in this project files a ticket without anyone pressing a button. Leave New feedback ticked under Receives which events — it is ticked by default, and it is the event auto-create fires on.
One connection can serve any number of projects, each pointing somewhere different. That is exactly what an agency with one Jira site and ten client projects needs.
Test connection runs in the connect panel before you save, and again any time from Manage on a saved connection. When a connection needs attention, its card and Manage say why in plain words with a What to do: line, and the button reads Test again. Either way it performs a lightweight, read-only call to confirm uMarker can reach the tracker and your destination:
| Provider | Health check |
|---|---|
| GitHub | GET /repos/{owner}/{name}: confirms the repo is reachable with the token. |
| Linear | A viewer GraphQL query: confirms the API key is valid. |
| Jira | GET /rest/api/3/myself: confirms the email + token authenticate. |
Disconnecting removes the stored credential. If projects are routing through it, uMarker refuses the first attempt and names them, so nobody’s tickets go quiet without warning. Confirm, and the connection and its routes are deleted together.
Issues already created stay linked: existing back-links on reports remain intact and clickable. Only new creations are blocked.
Once a project has a routed, active connection, open any report and press Create ticket. The button only appears when the project actually has a tracker routed to it. A CTA whose only job is to fail is worse than no CTA.
Open the report in the report detail view.
Press Create ticket. uMarker builds the issue from the report and submits it to the routed tracker.
On success, the report shows the new issue’s key as a back-link (e.g. #142, ENG-142, or MD-45) that opens the external issue directly.
| Report field | Where it lands |
|---|---|
| Title | GitHub/Linear title, Jira summary. Defaults to the comment, trimmed to 80 characters. |
| Description / body | The issue body (Jira as Atlassian Document Format). Carries the comment, page URL, a signed screenshot link, and a dashboard link. |
| Screenshot | A signed URL embedded in the body, included only when the report still has a screenshot. On a plan with a media retention window the link expires with it; see below. |
| Labels | The report’s labels, on GitHub only. Linear and Jira issues do not receive labels. |
The default body looks like this:
Reported via uMarker.
<the report's comment>
Page: https://site/checkoutScreenshot: https://api.umarker.com/… (link valid until 2027-01-12)Open in uMarker: https://app.umarker.com/s/8f2c…/feedback/42Page and Screenshot lines appear only when the report has those values.
uMarker checks for an existing link before submitting and re-checks under a row lock inside a database transaction, so a report is never linked to two issues. Two people pressing the button together end with one ticket — the second press waits for the first and finds the report already linked. Auto-create firing while somebody presses the button is the narrow exception: both can reach the tracker, only one of the two tickets is linked back, and the other is an orphan to close by hand. A report that’s already linked reports the existing key instead of creating another.
If the tracker rejects the request, nothing partial is stored (no key, no URL), and the report tells the triager the ticket could not be filed, which tracker refused, and whether trying again is likely to help. The provider’s exact reason is recorded on the connection instead, under Integrations, where an admin can read it as the connection’s last error:
| Tracker response | Reason recorded on the connection |
|---|---|
401 / 403 |
<Provider> rejected the credential — reconnect needed. |
404 |
<Provider> destination not found — check your configuration. |
429 |
<Provider> rate limit hit — try again shortly. |
| other | <Provider> returned HTTP <status>. |
A failing Test connection records the same reason in the same place, so an admin can reproduce the problem without waiting for the next report — or, when the tracker never answered at all, what stopped us reaching it.
This is not a one-way link. Point your tracker’s webhook at the URL shown on the connection, and closing the issue moves the uMarker report:
| Tracker event | Report becomes |
|---|---|
GitHub issue closed |
resolved, or archived if closed as not planned |
GitHub issue reopened |
in_progress |
Linear state completed / started / canceled |
resolved / in_progress / archived |
Jira status category done / indeterminate |
resolved / in_progress |
Jira is the one to read twice: those two categories are the only ones uMarker maps, and Jira has no cancelled category. If your workflow files “Cancelled” under the done category, that issue comes back as resolved, not archived.
The webhook URL carries a per-connection token, and nothing in the payload decides whose data is touched: the account and the set of projects come from the connection, resolved server-side. From the payload itself uMarker reads two things — the issue key, and the tracker’s own status for it. So whoever holds that URL can move the reports linked to that connection’s projects, and nothing beyond them. Treat it as a secret: the token is minted when the connection is created and there is no rotate button for it, so the only way to replace a leaked one is to disconnect and reconnect the tracker — which deletes its project routes with it. An unknown token gets 404; an event uMarker doesn’t act on is accepted and ignored, so your tracker never falls into a retry storm.
issue_linked eventA successful (non-duplicate) creation emits an issue_linked event to whatever the project routes it to (Slack, Telegram, Teams, or a signed webhook subscribed to that event), and raises an in-app notification, so a ticket filed automatically doesn’t happen in silence. See Outbound webhooks for the payload and Channels & routing to subscribe.
This part is for whoever runs the uMarker platform, not for tenants. Connect with Jira / GitHub / Linear appears only once you have registered an OAuth app with that provider and switched it on in the operator console. Until then, tenants connect with a token, and nothing dead is shown to them.
Open Integrations in the operator console and find OAuth apps — one-click connect. Each provider has a Redirect URL to register (exactly as shown) with a Copy button; register that URL with the provider character for character. It has the form {APP_URL}/api/integrations/oauth/{provider}/callback.
developer.atlassian.com/console/myapps.read:jira-work, write:jira-work and read:jira-user. offline_access is requested at sign-in so uMarker can refresh the token.github.com/settings/applications/new.repo scope.linear.app/settings/api/applications/new.Then switch on Offer to tenants and save. The row reads Live — tenants see the button; a configured app that isn’t offered reads Configured, not offered, and one with no app reads Not set up — token only. The client secret is write-only: leave it blank on a later save to keep the stored one. Every change is written to the audit log.