Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name

v2.0.0 · public · Published over 1 year ago

Asset Definition
Release Notes
Release Assets

Sensu Go Jira Handler

Bonsai Asset Badge
Go Test
Go Lint

Table of Contents


The Sensu Go Jira handler is a Sensu Event Handler that creates or updates a Jira issue.

Enterprise Plugin

The Sensu Go Jira Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Usage Examples


The Sensu Go Handler for managing Jira issues

  sensu-jira-handler [flags]
  sensu-jira-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

  -h, --help                                   help for sensu-jira-handler
  -T, --http-timeout uint                      The HTTP timeout
  -t, --jira-issue-type string                 The type of Jira issue to create
  -p, --jira-password string                   The Jira password
  -k, --jira-project-key string                The Jira project key
  -n, --jira-project-name string               The Jira project name
  -s, --jira-resolution-state string           The key of the status to transition the issue to when resolving it
  -d, --jira-issue-description string          The template to use to populate the issue description (default full event JSON)
  -c, --jira-issue-resolution-comment string   The template to use to populate the issue resolution comment (default "Sensu has resolved the event.")
  -U, --jira-url string                        The Jira URL
  -u, --jira-username string                   The Jira username
  -v, --verbose                                Verbose mode

Use "sensu-jira-handler [command] --help" for more information about a command.

Authenticating Using Jira's Cloud Version

While the on-premise version of Jira uses basic HTTP authentication with only
a simple username and password the cloud version requires the use of an API
token to authenticate
. To create the API token perform the following steps:

  1. Navigate to Atlassian's API Tokens Screen
  2. Click on the Create API Token button
  3. In the popup box enter Sensu Jira Handler or any label of your liking
  4. Click on the Create button
  5. Click on Copy to clipboard to copy your token

The token copied becomes the password you use to authenticate using the
JIRA_PASSWORD environment variable (preferably as a secret), or the
--jira-password option.

Resolving Issue Configuration

Unless a state is specified (either by --jira-resolution-state or via
annotation) when attempting to resolve an issue, this
handler will default to using the first transition state found in the Done
status category for that issue type.

To make sure this works, a screen with the Resolution needs to be configured
in the transition to the Done state. If this is not setup correctly the issue
resolution will fail.


Sensu Go

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not
using an asset, please consider doing so! If you're using sensuctl 5.13 with
Sensu Backend 5.13 or later, you can use the following command to add the asset:

sensuctl asset add sensu/sensu-jira-handler

If you're using an earlier version of sensuctl, you can find the asset on the
Bonsai Asset Index.

Handler definition

type: Handler
api_version: core/v2
  name: jira
  namespace: default
  type: pipe
  command: sensu-jira-handler --jira-url '' --jira-project-key SEN
  timeout: 10
  - sensu/sensu-jira-handler
  - is_incident
    secret: jira_username
    secret: jira_password

Environment Variables

Most arguments for this handler are available to be set via environment
variables. However, any arguments specified directly on the command line
override the corresponding environment variable.

Argument Environment Variable
--jira-url JIRA_URL
--jira-username JIRA_USERNAME
--jira-password JIRA_PASSWORD
--jira-project-key JIRA_PROJECT_KEY
--jira-project-name JIRA_PROJECT_NAME
--jira-issue-type JIRA_ISSUE_TYPE
--jira-resolution-state JIRA_RESOLUTION_STATE
--jira-issue-description JIRA_ISSUE_DESCRIPTION
--jira-issue-resolution-comment JIRA_ISSUE_RESOLUTION_COMMENT
--http-timeout HTTP_TIMEOUT
--verbose VERBOSE_MODE

Security Note: Care should be taken to not expose the API token for this
handler by specifying it on the command line or by directly setting the
environment variable in the handler definition. It is suggested to make use of
secrets management to surface it as an environment variable. The handler
definition above references it as a secret. Below is an example secrets
definition that make use of the built-in env secrets provider.

type: Secret
api_version: secrets/v1
  name: jira_username
  provider: env
type: Secret
api_version: secrets/v1
  name: jira_password
  provider: env

Templating Support

The --jira-issue-description and --jira-issue-resolution-comment options
allow the customization of the issue description and resolution comments using
Golang Templates. Within the templates all fields from the event
are available for use.

For example using "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}" would
produce the following:

webserver03/check-nginx: passing

Argument Annotations

All arguments for this handler are tunable on a per entity or check basis based
on annotations. The annotations keyspace for this handler is


To change the issue type for a particular check, for that checks's metadata
add the following:

type: CheckConfig
api_version: core/v2
  annotations: Bug

Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.


You must be signed in to report this asset.

Sign In with Github



There are no asset definitions for this version, only source code:

Download Source Cancel