Connect a ticket system

What's supported

• GitHub Issues, GitLab Issues, and Jira Cloud — supported, ship in v1.
• Azure DevOps, ServiceNow, Linear— experimental: code-complete and unit-tested, but not validated against a live instance, so dispatch refuses them (you'll see a skipped audit event with skip_reason=adapter_not_validated).

The common shape

Every integration target — whichever platform — is defined by the same four things, configured in the Workbench UI or via POST /api/integrations:

• platform — github / gitlab / jira.
• target_identity — which project/repo to file into (format differs per platform, below).
• base_url— the API host; empty means the platform's public cloud default, set it for self-managed / Enterprise.
• A credential (a token) and optional platform_options.

GitHub Issues

Credentials

A GitHub personal access token (classic or fine-grained) or a GitHub App installation token. A fine-grained PAT needs Issues: read & write on the target repo — mint it under Settings → Developer settings → Personal access tokens.

Target

• target_identity = owner/repo (e.g. acme/platform-issues).
• base_url = empty for github.com (defaults to https://api.github.com); set it for GitHub Enterprise.
• platform_options: assignees (usernames), milestone (numeric id), extra_labels.

curl -fsS -X POST "$WORKBENCH/api/integrations" \
  -b /tmp/wb.cookies \
  -H 'Content-Type: application/json' \
  -H "X-Arq-CSRF: $(grep arq_workbench_csrf /tmp/wb.cookies | awk '{print $7}')" \
  -d '{
        "platform": "github",
        "target_identity": "acme/platform-issues",
        "base_url": "",
        "platform_options": { "extra_labels": "elevarq,db-health" }
      }'

GitLab Issues

Works against gitlab.com and self-managed GitLab equally.

Credentials

A GitLab personal access token or project access token with the api scope (GitLab offers no narrower issues-only scope for the create-issue + note endpoints). Mint a PAT under User Settings → Access Tokens, or a project token under Project → Settings → Access Tokens.

Target

• target_identity = the numeric project ID (e.g. 481) or the namespace path (e.g. acme/platform or group/subgroup/project).
• base_url = empty for gitlab.com (defaults to https://gitlab.com/api/v4); for self-managed set your API base, e.g. https://gitlab.acme.internal/api/v4 (must be https://).
• platform_options: assignee_ids (numeric), milestone_id, confidential (mark the issue confidential), extra_labels.

Jira Cloud

Credentials

An Atlassian API token used as basic auth — the Atlassian user's email plus the generated token. Mint it at id.atlassian.com → Security → API tokens. The account needs Browse Projects + Create Issues + Add Comments + Create Attachments on the target project.

Target

• target_identity = the Jira project key (e.g. OPS).
• base_url = your Atlassian Cloud site, e.g. https://acme.atlassian.net.
• platform_options: the issue type to create (Bug, Story, …) — match your project's workflow.

Idempotency & audit

Every push is idempotent — a duplicate push for the same finding returns the existing ticket reference instead of opening a new one, so you can safely re-run a dispatch. Every attempt also emits a closed audit event at /audit-log:

• ticket.dispatch.success — accepted upstream.
• ticket.dispatch.failure — a terminal upstream error (carries a closed failure_kind).
• ticket.dispatch.skipped — refused before calling the adapter (idempotent_hit, license_refused, severity_below_threshold, adapter_not_validated).
• ticket.dispatch.retry — will retry (rate-limit, transport, 5xx).

No upstream response bodies leak into audit text.