Jira Cloud Notification Channel Setup for Alerts

Prerequisites

Before configuring Jira Cloud as a notification channel in SigNoz, ensure that you have:

• A Jira Cloud site: your site URL in the form https://<your-site>.atlassian.net. SigNoz appends the REST API path internally.
• Authentication: an Atlassian email + API token. We recommend a service account so issues aren't reported under a personal name and the channel doesn't break when someone leaves. See Use a service account. SigNoz authenticates with the email + token (basic auth).
• A project key and an issue type: e.g. project OPS and issue type Task. The issue type must exist in that project. Types vary per project, so Bug or Incident may not be available everywhere.
• Permissions: the account needs permission to create issues in the project (and to transition them, if you use resolve/reopen).

Use a service account (recommended)

We recommend authenticating with an Atlassian service account rather than a personal API token:

• Issues are reported under the service account's name, giving a clean audit trail.
• It survives team changes: nothing breaks when the person who set it up leaves or rotates their password.
• It uses no paid Jira seat and can be locked down to least privilege.

Creating one requires Organization admin access in Atlassian.

1. Create the service account

1. Go to admin.atlassian.com and select your organization.
2. Open Directory → Service accounts → Create service account.
3. Give it a clear name (e.g. signoz-alerts-service-account) and a description of what it's for.
4. Under app roles, grant Jira → User and leave everything else None.
5. Note the generated …@serviceaccount.atlassian.com email. Enter it as the username in SigNoz.

2. Give it access to your project

Atlassian treats the service account like a regular user, so add it to each project it will file issues in.

• Team-managed project: open the project → ••• → Add people → add the service account (search its name, or paste its full email) with the Member role.
• Company-managed project: Project settings → People → add it to a role (e.g. Member), and confirm the project's permission scheme grants that role Create Issues, Add Comments, and Transition Issues.

3. Create a scoped API token

1. In Directory → Service accounts, select the account → Create credentials → API token.
2. Name the token (e.g. signoz-jira-alert-channel) and set an expiry (1–365 days). Tokens don't auto-rotate, so put the renewal on a calendar.
3. Select the scopes read:jira-work and write:jira-work (filter the picker by App: Jira). These cover the full create / search / comment / transition lifecycle SigNoz uses.
4. Copy the token. It's shown only once.

4. Add it to SigNoz

When you create the channel (below), enter:

• Site URL: your https://<your-site>.atlassian.net
• Email: the service account's …@serviceaccount.atlassian.com address
• API token: the scoped token

SigNoz resolves your cloud ID and routes the service-account token automatically. You don't need to deal with cloud IDs or gateway URLs.

Accessing Notification Channels

To manage your notification channels in SigNoz, navigate to Settings > Notification Channels. This tab lists all configured channels.

Creating a new Notification channel

To create a new Jira notification channel:

• Navigate to Settings > Notification Channels and click on New Channel.
• Enter a Name for the channel and select Jira as the channel type.
• Site URL: your Jira Cloud base URL, e.g. https://your-domain.atlassian.net.
• Email: the account email used for authentication, either the service account's …@serviceaccount.atlassian.com (recommended) or a personal account email.
• API token: the token created above.
• Project key: e.g. OPS.
• Issue type: an issue type that exists in the project (defaults to Task).
• Summary (issue title) and Description: prefilled with default templates that control the created issue's title and body. You can edit them (see Customizing the message).
• Send resolved alerts: on by default. When on, SigNoz transitions the issue to a "done" status and comments on it when the alert resolves.

The Advanced Options section is optional. The required fields alone give a fully working channel:

• Priority: an issue priority that exists in the project's scheme (e.g. High). Leave empty to use the project default.
• Labels: extra labels to add to created issues. SigNoz always adds its own deduplication label as well (see Receive Alerts in Jira).
• Resolve transition / Reopen transition: name overrides for the workflow transitions. Auto-detected by default. Only set these if your project has more than one "done" transition and you want to force a specific one by name.
• Reopen window: how long after resolution a re-firing alert reopens the same issue (see Issue lifecycle and transitions).

Test Configuration: Click the Test button to open a real issue end-to-end in the configured project. This verifies that SigNoz can authenticate and create issues before you save.

Editing a Notification channel

To edit an existing Jira channel, open it from the channels list. You can change the Site URL, Email, API token, Project key, Issue type, Summary, Description, Send resolved alerts toggle, and the Advanced Options. The channel Name and Type cannot be changed after creation.

Receive Alerts in Jira

Once configured, SigNoz manages a Jira issue over the full lifecycle of each alert.

• An alert firing creates a Jira issue. The description is built as Atlassian Document Format (ADF) (the rich-text format Jira Cloud's v3 API uses) with:
  • A status panel: 🔴 FIRING (red) or 🟢 RESOLVED (green).
  • The rendered alert details.
  • Deep-link(s) back to SigNoz: Open in SigNoz, and View Related Logs / View Related Traces when the alert carries those links.

• The same alert re-firing updates that issue instead of creating a duplicate. SigNoz correlates alerts to issues with an auto-added label of the form ALERT{…}. Do not remove this label, or SigNoz will no longer find the issue and will open a new one.
• On each state change, SigNoz posts a comment carrying the current snapshot (Jira has no threads, so comments form the timeline): a re-fire adds a "still firing" comment, a resolve adds a "resolved" comment, and a reopen adds a "re-firing, reopening" comment. Issue creation posts no comment. The issue itself is the record. Comments fire per notification (roughly the re-notify interval), not per rule evaluation, so a long-firing alert gets a periodic timeline rather than spam.

Grouped alerts

When several alerts fire together, they are grouped into a single issue whose body lists every alert in the group, with one set of deep-links. This keeps grouped notifications compact.

Limits handled automatically

• The issue summary is capped at 255 characters and the description at ~32 KB. SigNoz truncates anything larger before sending.
• Rate-limited requests (429) are retried automatically.

Issue lifecycle and transitions

When an alert resolves, SigNoz transitions the issue to a "done" status; when a resolved alert fires again within the reopen window, SigNoz reopens it (moves it back out of "done").

Transitions are matched by Jira's status category (new / indeterminate / done), not by hardcoded status names, so this works across any custom workflow:

• The Resolve transition moves the issue into the done category; the Reopen transition moves it back out.
• Set a name override (in Advanced Options) only when a project has more than one matching transition, e.g. both Done and Won't Do land in done and you want to force one.
• If no suitable transition exists, SigNoz skips the transition without erroring and still posts the comment.

Reopen window

The Reopen window controls how long after resolution a re-firing alert reopens the same issue:

• If a resolved alert fires again within this window, the same issue is reopened.
• After the window, a re-fire opens a new issue instead.

Enter it as a duration using the units m (minutes), h (hours), d (days), w (weeks), or y (years), e.g. 30m, 72h, or 3d. The minimum is 1m and the default is 3d.

Customizing the message

The Summary is the issue title (plain text). The Description is written in standard markdown, which SigNoz renders into ADF for the issue body. Both accept Go templates.

The following markdown constructs are supported:

• Render as rich text: bold, italic, strikethrough, links, inline code, fenced and indented code blocks, headings, blockquotes, ordered/unordered/nested lists, and horizontal rules.
• Not rendered: tables (their content falls back to plain text) and images (dropped).

The default templates use only bold and text, so this only matters if you write a fully custom Description.

Turn-off Resolved alerts

The Send resolved alerts toggle is on by default. When on, a resolved alert transitions the issue to a "done" status and adds a 🟢 RESOLVED comment.

To stop SigNoz from transitioning issues on resolve:

• Navigate to Settings > Notification Channels.
• Click Edit on the channel.
• Toggle off Send resolved alerts and click Save.

With the toggle off, issues are created and updated while firing but are not automatically transitioned to "done" when the alert resolves.

Configure programmatically

You can also configure the Jira notification channel using the SigNoz API.

API Endpoint: POST /api/v1/channels

Send a POST request to /api/v1/channels with the following curl command. Replace <your-api-key> with an API key from Settings → Service Accounts (see Service Accounts to create one).

curl '<your-signoz-url>/api/v1/channels' \
  -H 'SIGNOZ-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "name": "Prod Critical Alerts - Jira",
    "jira_configs": [
        {
            "send_resolved": true,
            "site": "https://your-domain.atlassian.net",
            "project": "OPS",
            "issue_type": "Task",
            "http_config": {
                "basic_auth": {
                    "username": "you@example.com",
                    "password": "<your-api-token>"
                }
            },
            "summary": "[{{ .Status | toUpper }}{{ if eq .Status \"firing\" }}:{{ .Alerts.Firing | len }}{{ end }}] {{ .CommonLabels.alertname }}",
            "description": "{{ range .Alerts -}}\n**Alert:** {{ .Labels.alertname }}{{ if .Labels.severity }} ({{ .Labels.severity }}){{ end }}{{ if .Annotations.summary }}\n**Summary:** {{ .Annotations.summary }}{{ end }}{{ if .Annotations.description }}\n**Description:** {{ .Annotations.description }}{{ end }}\n{{ end }}",
            "reopen_duration": "3d"
        }
    ]
}'

Request Body Attributes:

Troubleshooting

If you encounter issues:

• 401 / 403 → the API token is wrong or the account lacks permission on the project. Re-check the email + token and the project permissions.
• 401 / 403 with a service account → confirm you used the service account's …@serviceaccount.atlassian.com email, added the account to the project, and gave the token the read:jira-work and write:jira-work scopes.
• 400 on create → a field required by that project's issue type is missing, or the project / issue type / priority is invalid. Check the project's create screen.
• "can't find transition" → only relevant when a transition-name override is set and doesn't match the workflow. Clear the override to fall back to auto-detection.
• Invalid Site URL → the URL must be an https URL on an atlassian.net domain.
• Invalid Reopen window → use a duration like 30m, 72h, or 3d (minimum 1m).
• Test the setup: use the Test button in SigNoz to create an issue end-to-end. If it fails, the error identifies the misconfigured field.

Next steps

• Create an alert rule and route it to this channel: Manage Alerts
• Set up more notification channels: Notification Channels