External Trackers & Tools

This page describes the namespace-scoped tracker integrations used to create and mirror issues, receive issue webhooks, and attach development evidence. For network topology (resolver nodes, runner agents, MCP server), see the Integrations Guide.

Once an integration is configured, authorized users can send findings or Mockarty Tasks issues to that provider. Explicitly mirrored issues retain their upstream link; supported inbound webhooks then keep selected fields and development evidence current.

Supported trackers

Allure TestOps catalogue refresh

An Allure namespace connection with forward_pull: true refreshes case names,
descriptions and tags from its configured base_url and numeric project_id.
The pull reads the full catalogue on each pass. It preserves case identity
across renames and distinguishes projects on different TestOps servers.
Cleared source descriptions and tags are also cleared in these imported cases.
Manually detached cases are not adopted again automatically.

Transient source responses (429, 502, 503, 504) and read connection
failures are retried at most twice. The pull respects Retry-After; a requested
wait over 30 seconds ends the current pass and leaves the cursor unchanged for
the next scheduled attempt. Result uploads and token exchanges are not replayed.

This refresh does not migrate the complete TestOps project: steps, media,
workflows, history and run relationships require further migration support.
Duplicate titles that conflict with an existing case are reported as errors.
Older imported rows without a server binding block automatic refresh until
an explicit source mapping is provided; do not delete them to bypass the check.
The stored-token connection and the version of TestOps in use must be verified
before enabling this on a working catalogue.

If TestOps is unreachable and you need to stop a saved connection immediately,
send PATCH /api/v1/namespaces/{namespace}/integrations/{id} with
{"enabled":false}. This keeps its saved configuration and credential. The
request does not need to resolve the existing TestOps host; changing the host
or other connection details still requires normal validation.

Authentication for catalogue refresh

Set auth_mode in the Allure connection configuration:

• bearer (also used when omitted): the saved credential is already an access
  token. Mockarty sends it directly as Bearer authorization.
• api_token: the saved credential is a personal API token. Mockarty exchanges
  it for a short-lived access token using the configured TestOps server, then
  uses that access token for catalogue requests. It renews the cached token
  before its reported expiry. If TestOps does not report a lifetime, the token
  is used without caching.

Example connection configuration; store the credential separately:

{
  "base_url": "https://testops.example.com",
  "project_id": 7,
  "forward_pull": true,
  "auth_mode": "api_token"
}

Use the exact TestOps origin (scheme and hostname, with an optional port),
without a path or query. Redirects are rejected. The exchange follows the
Allure TestOps API authentication documentation.
Confirm compatibility with your TestOps version before enabling refresh.

With api_token, Test connection checks project access through the current
TestOps API. Case and launch links use its project-scoped detail endpoints;
case search uses TestOps AQL. The legacy bearer mode keeps the existing
link and search protocol. A successful connection check verifies access, not
the completeness of a migration.

Adding an integration

1. Open Security, open a finding, and select a provider under Send to tracker.
2. Click Send. If that provider is not configured, Mockarty opens the External trackers settings modal instead of sending.
3. Fill in the adapter-specific config (base URL, project key, …) and paste the API token.
4. Click Save. The Test connection button is enabled after the configuration exists.
5. Click Test connection — Mockarty runs a minimal API call against the target and stores the latest verdict.

Saved tokens are write-only: the UI and API never return their value. They are encrypted at rest when the administrator configures Mockarty’s PII encryption key.

What Mockarty stores

Stored credentials for namespace integrations

When configuring a namespace integration through the API or MCP, secretsRef
is the UUID of a credential already saved in Mockarty. It is not the token
itself. Invalid and all-zero UUIDs are rejected. When updating a connection,
omit secretsRef to keep its credential or send an empty string to detach it.
Use Test connection after changing credentials.

• Configuration belongs to one namespace and one provider.
• Token and webhook-secret values are write-only; API responses expose only whether each secret is set.
• Mirroring creates an explicit link between the local issue and the upstream issue. It does not turn arbitrary text containing an issue-like key into a synchronized record.
• Development webhooks add canonical HTTP(S) links to branches, commits, merge or pull requests, and pipelines.

Required permissions

Troubleshooting

Test credentials failed (401 / 403). Token expired or lacks required scopes. Reissue with the scopes above.

Test credentials failed (network timeout). Verify the admin node can reach the tracker URL directly. Behind a proxy, export HTTPS_PROXY for Mockarty server and restart.

A mirrored issue does not update. Check that the provider-specific issue webhook URL and secret are configured and that the relevant issue/comment events are enabled upstream.

Send to Tracker (one-click ticket creation)

Available from the Security Agent’s finding detail modal. Promotes a security finding into a ticket in your existing tracker with a single click — the finding’s title, severity, scanner, CVE/CWE, CVSS score, evidence, remediation guidance, and AI analysis are auto-formatted into the issue body. A deep-link back to Mockarty is also included so the ticket can be traced back to the original finding.

Supported trackers

How to use

1. Open any security finding in the Security page.
2. In the finding detail modal, find the Send to tracker row below the bug URL field.
3. Select the tracker from the dropdown (Jira / Linear / GitHub / GitLab).
4. Click Go.
5. The ticket is created and its URL is auto-filled into the bug tracker URL field.

What is included in the ticket

The issue body follows a standard template:

## {title}
{description}

| Field    | Value     |
|----------|-----------|
| Scanner  | sql_inj   |
| Severity | critical  |
| CVE      | CVE-2024  |
| CWE      | CWE-89    |
| CVSS     | 9.8       |
| Target   | /api/...  |

### Evidence

{raw evidence}

### Remediation
{fix guidance}

### AI Analysis
{LLM analysis summary}

---
[Mockarty finding]({url}) · ID: {id}

Configuration

Tracker credentials are stored per namespace. To configure:

1. Open Security, open a finding, select the provider under Send to tracker, and click Send. For an unconfigured provider Mockarty opens the settings modal without creating a ticket.
2. Fill in:
   • URL — Jira: https://company.atlassian.net, Linear: https://api.linear.app. GitHub: leave empty for github.com (GitHub Cloud); for GitHub Enterprise Server enter your install’s address, e.g. https://github.company.com (Mockarty routes to its /api/v3 API automatically). GitLab: enter the GitLab installation URL, for example https://gitlab.com or https://gitlab.company.com; Mockarty appends /api/v4 automatically.
   • Token — Jira API token, Linear personal key, GitHub PAT, or GitLab access token
   • Project — Jira: project key (SEC), Linear: team key, GitHub: owner/repo, GitLab: project path (team/app) or numeric project ID
   • Email (Jira only) — the Atlassian account email that owns the API token
   • Issue type (Jira only) — Bug (default), Task, or Story
   • Labels — comma-separated, auto-applied to every created ticket
3. Click Test credentials to verify.
4. Save.

Two-way sync (inbound webhook)

When you mirror a Mockarty Tasks issue out to Jira, GitHub, or GitLab, the link is remembered. Two-way sync closes the loop: a change made in the external tracker (status moved, title edited, comment added) flows back to the mirrored Mockarty issue automatically — no manual re-import.

How to set it up

1. Open the External trackers modal as described above and expand Two-way sync (inbound webhook) on the Jira, GitHub, or GitLab card.
2. Copy the Webhook URL shown there. It looks like:
   https://your-mockarty/api/v1/public/issuetracker/<namespace>/webhook/jira
3. Click Generate to create a Webhook secret, then Save. The secret is shown once — copy it now; afterwards Mockarty only tells you that a secret is set, never the value.
4. In your external tracker, add a webhook pointing at that URL:
   • Jira — Project settings → Webhooks → Create. Paste the URL, and add the secret as a request header X-Mockarty-Webhook-Secret. Subscribe to Issue updated and Comment created.
   • GitHub — Repository settings → Webhooks → Add webhook. Paste the URL as the Payload URL, paste the secret into the Secret field (GitHub signs each delivery), content type application/json, and select Issues and Issue comments events.
   • GitLab — Project → Settings → Webhooks. Paste the URL, paste the secret into Secret token, and enable issue and comment/note events. GitLab sends the token in X-Gitlab-Token.

What syncs in

Status names are matched flexibly: Done / Closed / Resolved → Done, In Progress / Doing → In Progress, In Review / QA / Testing → In Review, To Do / Backlog / Open → To Do. A status name that doesn’t match any column is left unchanged.

Deliveries with a missing or wrong secret are rejected. An event for an issue that was never mirrored is ignored.

Development links on an issue

The GitHub and GitLab integration cards also show a separate Code links webhook URL. Add it to the repository/project with the same provider-scoped secret. Include a Mockarty issue key in a branch name, for example ABC-12-fix-login. Pushes, pull/merge requests, and CI runs that carry that branch are then linked to the issue automatically.

Open the issue detail panel to see the links grouped as Branches, Commits, Merge requests, and Pipelines, including the upstream state when the provider sends one. Each group initially shows up to six entries; Show all expands only that group.

Importing issues into Mockarty Tasks

Two import paths bring existing issues into a namespace’s tracker. Both accept
either a raw JSON body or a multipart file upload (up to 10 MiB), and both
map types, statuses and priorities onto Mockarty’s built-ins automatically.

From Jira

curl -X POST "http://localhost:5770/api/v1/namespaces/<ns>/issuetracker/import/jira" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @jira-export.json

The payload is the canonical Jira REST search shape ({"issues":[…]}) — what
the Jira API returns. Projects are created from the issue key prefixes; parent
links and comments come along. POST .../import/jira/pull pulls issues live
from a configured Jira connection instead of a file.

From another Mockarty namespace (merge)

Export a project from the source namespace, then import it into the target —
this is how two teams’ trackers merge when namespaces are consolidated:

# 1. In the source namespace: export the project as JSON
curl ".../namespaces/<source-ns>/issuetracker/projects/<projectId>/export?format=json" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" -o project.json

# 2. In the target namespace: merge it in
curl -X POST ".../namespaces/<target-ns>/issuetracker/import/mockarty" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @project.json

The target project is found or created by its key prefix; parent/child links
are preserved. The merge is idempotent: issues already imported (matched by
their source key) are skipped, so re-running the same import never duplicates —
the response reports alreadyPresent alongside issuesCreated.

What comes across. Title, description, type, status, resolution, priority,
labels, parent links — and the planning data a person entered: story points,
start and due dates, original and remaining estimates, the environment note,
and your custom fields.

What does not, and why. Sprints and workflow states name things that exist
only in the source namespace — the target has its own, so an issue carrying
them would point at nothing. Board rank and issue numbers are positional and
are assigned fresh. Assignee and reporter are carried as written; if those
users do not exist in the target namespace, the fields keep the raw value
rather than silently emptying, so nothing is lost while you reconcile
accounts.