Skip to main content
Version: 0.4 · current

Create Jira issues from alerts

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin, Installer (Linux administrator)
PlansPro · EnterpriseDeploymentSelf-hosted

With Jira connected, an operator turns an alert or a security finding into a Jira issue with one click. The issue is prefilled with everything Excubius knows, its key is stored on the alert, and its status is followed until it is done. This guide shows how to connect Jira Cloud, how to send each client to its own project, and what the issue contains.

Before you begin​

  • A Jira Cloud site. Jira Server and Data Center are not supported.
  • An Atlassian account for Excubius with these permissions in the target projects: Browse projects, Create issues, Add comments and Link issues. No administration right is needed: Excubius never transitions, edits or deletes issues.
  • The feature collab.jira is on in Settings › Instance. It requires collab.assign. A super admin switches it.
  • To set server-wide defaults, you need access to the server configuration. To set an entity's own Jira settings, you need the Entity admin role on it.

There is no Jira settings screen in the console in this release: you set the defaults in the server configuration and per-entity settings through the API.

Choose how Excubius signs in to Jira​

authCredentialsUse it when
token (default)The account's e-mail address and an API tokenThe usual case: a dedicated Atlassian account with an API token
oauthThe client ID and client secret of an Atlassian service account, plus the site's cloud IDYour organisation uses Atlassian service accounts with OAuth 2.0 client credentials. The API is then reached at https://api.atlassian.com/ex/jira/<cloud_id>
bearerA token sent as isA personal access token behind a gateway

Find the cloud ID of a site at https://<site>.atlassian.net/_edge/tenant_info.

Set the defaults on the server​

The defaults apply to every entity that does not set its own.

  1. Connect to the server and become the service account with sudo -iu excubius.

  2. Add the settings to /opt/excubius/.env. For the default token authentication:

    JIRA_BASE_URL=https://areito.atlassian.net
    JIRA_EMAIL=monitoring@areito.example
    JIRA_API_TOKEN=<API token>
    JIRA_DEFAULT_PROJECT=OPS
    JIRA_ISSUE_TYPE=Task

    For oauth, set JIRA_AUTH=oauth, JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRET and JIRA_CLOUD_ID instead of the e-mail and API token.

  3. Restart the platform:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

Send a client to its own project​

Each entity can set any of the Jira keys for itself. The setting is inherited down the tree key by key: the nearest entity that sets a key wins. So one Jira site can serve every client, each with its own project and credential.

  1. Store the Jira credential on the entity: open Settings › Credentials, choose the entity, for example Ciguapa Inc., and add a credential of kind HTTP user and password (the e-mail and API token, or the OAuth client ID and secret) or Bearer token. The secret is stored encrypted and never shown again.

  2. Set the entity's keys through the API. $BASE is https://<your server>/api/v1 and H holds your token, as in Quickstart: add a SQL Server instance with the API:

    curl -s "${H[@]}" -X PUT "$BASE/entities/$CIGUAPA/jira" -d '{
    "project_key": "CIG", "issue_type": "Task",
    "credential_id": "'"$JIRA_CRED"'", "labels": ["monitoring"]
    }'
  3. Check what applies and where each key comes from. The answer says whether the entity is configured and, if not, what is missing in problem:

    curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}'
  4. Test the connection. The test only reads: who the credential is in Jira, the project and its issue types.

    curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/jira/test"

To put a key back to the inherited value, send it as null. DELETE /entities/{id}/jira removes all of the entity's own keys.

KeyDefaultMeaning
base_urlJIRA_BASE_URLhttps://<site>.atlassian.net
authJIRA_AUTH, token when not settoken, oauth or bearer
credential_idThe e-mail and token, or OAuth client, from the server configurationA credential of this entity or an ancestor: HTTP user and password for token and oauth, Bearer token for bearer
cloud_idJIRA_CLOUD_IDFor oauth only
project_keyJIRA_DEFAULT_PROJECTWhere issues go, such as OPS
issue_typeJIRA_ISSUE_TYPE, Task when not setThe issue type's name in that project
priority_mapcritical → High, warning → Medium, info → LowSeverity to Jira priority name
labelsNoneExtra labels, without spaces
summary_prefixThe product name in bracketsText before the summary; an empty text for none
synctrueFollow the issue's status
done_commenttrueComment on the issue when it is done, saying whether the condition is still detected
resolve_events_on_donetrueResolve event alerts, such as a change in privileged group members, when their issue is done

Create an issue​

  1. In the Alert inbox, select the alert. For a security finding, open it on the Security posture page.
  2. Select Create Jira ticket. You need the Operator role or higher.

Excubius confirms Jira ticket OPS-123 created and stores the key on the alert, where everyone sees it. An alert gets at most one issue: asking again returns the existing key.

The issue contains:

  • Summary: the prefix, the alert's title and the resource.
  • Description: severity, category and status; first and last seen; the resource with its entity path, criticality, tags and identifying details such as host, version and availability group; the check's value against the threshold and where that threshold is set; for a finding, its evidence; the baseline reference; the last ten timeline events; the suggested action, marked as a suggestion; and links back to the alert and the resource.
  • Labels: the product name, the category (alert, finding, advisory), the severity and your extra labels.
  • Priority: from the severity through priority_map. When the project does not accept a priority, the issue is created without one.
  • A link on the issue back to the alert.

Follow the issue's status​

Every 10 minutes Excubius reads the status of up to 100 open issues, least recently checked first. JIRA_SYNC_MINUTES changes the interval. When an issue reaches a status of the Done category:

  • The alert's timeline records it.
  • An event alert, such as a change in sysadmin members, is resolved: the change was reviewed.
  • Other alerts are not resolved by the issue. They resolve when the next check no longer detects the condition, and the comment on the issue says whether it is still detected.

An expired token or a deleted issue is recorded and retried at the next sync. The issue is not followed after it is done.

Limitations​

  • The status is polled; Jira webhooks back to Excubius are not used yet.
  • OAuth 2.0 is the client-credentials flow of an Atlassian service account. Per-user OAuth is not supported.
  • Jira Server and Data Center are not supported.