Jira¶
You can import tasks from your Jira instance using
the jira
service name.
Additional Requirements¶
Install the following package using pip
:
jira
Example Service¶
Here’s an example of a jira project:
[my_issue_tracker]
service = jira
jira.base_uri = https://bug.tasktools.org
jira.username = ralph
jira.password = 8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903
[my_issue_tracker]
service = "jira"
base_uri = "https://bug.tasktools.org"
username = "ralph"
password = "8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903"
Note
The base_uri
must not have a trailing slash.
Note
Basic authentication with passwords is deprecated. The password may contain an api token or alternatively you can set PAT to a Personal Access Token.
The above example is the minimum required to import issues from Jira. You can also feel free to use any of the configuration options described in Common Service Configuration Options or described in Service Features below.
Service Features¶
The following default configuration is used:
# jira.body_length = <sys.maxsize>
jira.import_labels_as_tags = False
jira.import_sprints_as_tags = False
jira.label_template = {{label}}
jira.query = assignee = <jira.username> AND resolution is null
jira.use_cookies = False
jira.verify_ssl = True
jira.version = 5
# jira.body_length = <sys.maxsize>
import_labels_as_tags = false
import_sprints_as_tags = false
label_template = "{{label}}"
query = "assignee = <jira.username> AND resolution is null"
use_cookies = false
verify_ssl = true
version = 5
Specify the Query to Use for Gathering Issues¶
By default, the JIRA plugin will include any issues that are assigned to you
but do not yet have a resolution set, but you can fine-tune the query used
for gathering issues by setting the query
parameter.
For example, to select issues assigned to ‘ralph’ having a status that is not ‘closed’ and is not ‘resolved’, you could add the following configuration option:
jira.query = assignee = ralph and status != closed and status != resolved
query = "assignee = ralph and status != closed and status != resolved"
This query needs to be modified accordingly to the literal values of your Jira instance; if the name contains any character, just put it in quotes, e.g.:
jira.query = assignee = 'firstname.lastname' and status != Closed and status != Resolved and status != Done
query = "assignee = 'firstname.lastname' and status != Closed and status != Resolved and status != Done"
Jira v4 Support¶
If you happen to be using a very old version of Jira, add the following configuration option to your service configuration:
jira.version = 4
version = 4
Do Not Verify SSL Certificate¶
If you want to ignore verifying the SSL certificate, set:
jira.verify_ssl = False
verify_ssl = false
Kerberos authentication¶
If the password
is specified as @kerberos
, the service plugin will try
to authenticate against server with kerberos. A ticket must be already present
on the client (created by running kinit
or any other method).
Synchronizing Issue Content¶
By default, this service synchronizes the description of the Jira issue as jiradescription
.
In some cases, this is not required.
It also risks triggering bugs in Taskwarrior around unicode encodings.
Set body_length`
to limit the size of the description UDA or include jiradescription
in static_fields
in the [general]
section to eliminate the UDA entirely.
When using API token¶
Some hosts only support API tokens to authenticate. If so, bugwarrior pull
will respond with Err: 401 Unauthorized
. Create a token. Handle the token like it is a password.
Note that if given a correct API token and an incorrect username, Jira will authenticate successfully but not allow access to any issues.
When using Personal Access Token¶
Some hosts only support Personal Access Tokens (PATs) to authenticate. If so, bugwarrior pull
will respond with Err: 401 Unauthorized
. Create a PAT as described here.
Put the PAT in the PAT
field and do not set password
.
Provided UDA Fields¶
Field Name |
Description |
Type |
---|---|---|
jiracreatedts |
Created At |
Date & Time (date) |
jiradescription |
Jira Description |
Text (string) |
jiraestimate |
Estimate |
Number (numeric) |
jirafixversion |
Fix Version |
Text (string) |
jiraid |
Jira Issue ID |
Text (string) |
jiraissuetype |
Issue Type |
Text (string) |
jiraparent |
Jira Parent |
Text (string) |
jirastatus |
Jira Status |
Text (string) |
jirasubtasks |
Jira Subtasks |
Text (string) |
jirasummary |
Jira Summary |
Text (string) |
jiraurl |
Jira URL |
Text (string) |
Support for Extra UDA Fields¶
To export additional UDA fields, set extra_fields
to comma-separated entries of the form uda_tag:field_key[.subkey]
. You can also chain subkeys to extract deeply embedded keys, e.g.:
jira.extra_fields = jiraextrafield1:customfield_10000, jiraextrafield2:customfield_10001.attributes.description
extra_fields = "jiraextrafield1:customfield_10000, jiraextrafield2:customfield_10001.attributes.description"
The correct key (and subkeys) can be found by inspecting the fields attribute of a standard Jira issue response.