community.general.jira module – Create and modify issues in a JIRA instance

Note

This module is part of the community.general collection (version 12.6.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.jira.

Synopsis

• Create and modify issues in a JIRA instance.

Parameters

Parameter	Comments
account_id string added in community.general 2.5.0	Sets the account identifier for the assignee when operation is create, transition, or edit. Note that JIRA may not allow changing field values on specific transitions or states.
assignee string	Sets the assignee when operation is create, transition, or edit. Jira Cloud requires account IDs for all user-type fields. When cloud=true, a string value containing @ is resolved as an email to an account ID automatically. A string without @ is assumed to be an account ID. See also account_id for a dedicated assignee account ID parameter. Added in community.general 12.6.0. Jira Server and Jira Data Center may still accept assignee as a username. Note that JIRA may not allow changing field values on specific transitions or states.
attachment dictionary added in community.general 2.5.0	Information about the attachment being uploaded.
content string	The Base64 encoded contents of the file to attach. If not specified, the contents of attachment.filename is used instead.
filename path / required	The path to the file to upload (from the remote node) or, if attachment.content is specified, the filename to use for the attachment.
mimetype string	The MIME type to supply for the upload. If not specified, best-effort detection is performed.
client_cert path added in community.general 10.4.0	Client certificate if required. In addition to username and password or token. Not mutually exclusive.
client_key path added in community.general 10.4.0	Client certificate key if required. In addition to username and password or token. Not mutually exclusive.
cloud boolean added in community.general 12.6.0	Enable when using Jira Cloud. When set to true, the module uses Jira Cloud compatible behavior. When set to false (the default), the module uses Jira Server / Data Center compatible behavior. In the future, this option might affect additional operations for Jira Cloud compatibility. Choices: false ← (default) true
comment string	The comment text to add. Note that JIRA may not allow changing field values on specific transitions or states.
comment_visibility dictionary added in community.general 3.2.0	Used to specify comment comment visibility. See https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post for details.
type string / required	Use comment_visibility.type to specify which of the JIRA visibility restriction types is used. Choices: "group" "role"
value string / required	Specify value corresponding to the type of visibility restriction. For example name of the group or role.
custom_user_fields list / elements=string added in community.general 12.6.0	A list of field names (for example customfield_10050) that hold user values. When cloud=true and a listed field is present in fields as a string containing @, the module resolves the email to a Jira Cloud account ID automatically. The built-in user fields assignee and reporter are always resolved when present; list here any further user-typed fields (from other Jira products or extensions) that should receive the same resolution. Default: []
description string	The issue description, where appropriate. Note that JIRA may not allow changing field values on specific transitions or states.
fields dictionary	This is a free-form data structure that can contain arbitrary data. This is passed directly to the JIRA REST API (possibly after merging with other required data, as when passed to create). See examples for more information, and the JIRA REST API for the structure required for various fields. When cloud=true, user-type fields (assignee, reporter, and any fields listed in custom_user_fields) that contain a string value with @ are automatically resolved from email to account ID. String values without @ are assumed to be account IDs. Added in community.general 12.6.0. When passed to comment, the data structure is merged at the first level since community.general 4.6.0. Useful to add JIRA properties for example. Note that JIRA may not allow changing field values on specific transitions or states. Default: {}
inwardissue string	Set issue from which link is created.
issue aliases: ticket string	An existing issue key to operate on.
issuetype string	The issue type, for issue creation.
jql string added in community.general 0.2.0	Query JIRA in JQL Syntax, for example "CMDB Hostname" = test.example.com.
linktype string	Set type of link, when action ‘link’ selected.
maxresults integer added in community.general 0.2.0	Limit the result of operation=search. If no value is specified, the default JIRA limit is used. Used when operation=search only, ignored otherwise.
operation aliases: command string / required	The operation to perform. worklog was added in community.general 6.5.0. Choices: "attach" "comment" "create" "edit" "fetch" "link" "search" "transition" "update" "worklog"
outwardissue string	Set issue to which link is created.
password string	The password to log-in with. Must be used with username. Mutually exclusive with token.
project string	The project for this operation. Required for issue creation.
status string	Only used when operation is transition, and a bit of a misnomer, it actually refers to the transition name. This is mutually exclusive with status_id.
status_id string added in community.general 10.3.0	Only used when operation is transition, and refers to the transition ID. This is mutually exclusive with status.
summary string	The issue summary, where appropriate. Note that JIRA may not allow changing field values on specific transitions or states.
timeout float	Set timeout, in seconds, on requests to JIRA API. Default: 10.0
token string added in community.general 4.2.0	The personal access token to log-in with. Mutually exclusive with username and password.
uri string / required	Base URI for the JIRA instance.
username string	The username to log-in with. Must be used with password. Mutually exclusive with token.
validate_certs boolean	Require valid SSL certificates (set to false if you would like to use self-signed certificates). Choices: false true ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: none	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

• Currently this only works with basic-auth, or tokens.

• To use with JIRA Cloud, pass the login e-mail as the username and the API token as password.

• Jira Cloud has removed the legacy /rest/api/2/search endpoint. Set cloud=true when using operation=search against Jira Cloud so that the module uses the replacement /rest/api/2/search/jql endpoint instead.

Examples

# Create a new issue and add a comment to it:
- name: Create an issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: create
    summary: Example Issue
    description: Created using Ansible
    issuetype: Task
  args:
    fields:
      customfield_13225: "test"
      customfield_12931: {"value": "Test"}
  register: issue

- name: Comment on issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: comment
    comment: A comment added by Ansible

- name: Comment on issue with restricted visibility
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: comment
    comment: A comment added by Ansible
    comment_visibility:
      type: role
      value: Developers

- name: Comment on issue with property to mark it internal
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: comment
    comment: A comment added by Ansible
    fields:
      properties:
        - key: 'sd.public.comment'
          value:
            internal: true

# Add an workog to an existing issue
- name: Worklog on issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: worklog
    comment: A worklog added by Ansible
    fields:
      timeSpentSeconds: 12000

- name: Workflow on issue with comment restricted visibility
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: worklog
    comment: A worklog added by Ansible
    comment_visibility:
      type: role
      value: Developers
    fields:
      timeSpentSeconds: 12000

- name: Workflow on issue with comment property to mark it internal
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: worklog
    comment: A worklog added by Ansible
    fields:
      properties:
        - key: 'sd.public.comment'
          value:
            internal: true
      timeSpentSeconds: 12000

# Assign an existing issue using edit
- name: Assign an issue using free-form fields
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key}}'
    operation: edit
    assignee: ssmith

# Create an issue with an existing assignee
- name: Create an assigned issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: create
    summary: Assigned issue
    description: Created and assigned using Ansible
    issuetype: Task
    assignee: ssmith

# Assign an issue on Jira Cloud using an email address
# (the module resolves the email to an account ID automatically)
- name: Assign an issue on Jira Cloud using email
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: edit
    cloud: true
    assignee: user@example.com

# Create an issue on Jira Cloud with reporter and a custom user field
# resolved from email addresses to account IDs
- name: Create an issue on Jira Cloud with user field resolution
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: create
    summary: Example Issue
    description: Created using Ansible
    issuetype: Task
    cloud: true
    assignee: assignee@example.com
    custom_user_fields:
      - customfield_10050
  args:
    fields:
      reporter: reporter@example.com
      customfield_10050: approver@example.com

# Edit an issue
- name: Set the labels on an issue using free-form fields
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: edit
  args:
    fields:
      labels:
        - autocreated
        - ansible

# Updating a field using operations: add, set & remove
- name: Change the value of a Select dropdown
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: update
  args:
    fields:
      customfield_12931: ['set': {'value': 'Virtual'}]
      customfield_13820: ['set': {'value': 'Manually'}]
  register: cmdb_issue
  delegate_to: localhost


# Retrieve metadata for an issue and use it to create an account
- name: Get an issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: fetch
    issue: ANS-63
  register: issue

# Search for an issue on Jira Data Center / Server
# You can limit the search for specific fields by adding optional args. Note! It must be a dict, hence, lastViewed: null
- name: Search for an issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: search
    maxresults: 10
    jql: project=cmdb AND cf[13225]="test"
  args:
    fields:
      lastViewed:
  register: issue

# Search for an issue on Jira Cloud (uses the /search/jql endpoint)
- name: Search for an issue on Jira Cloud
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    project: ANS
    operation: search
    cloud: true
    maxresults: 10
    jql: project=cmdb AND cf[13225]="test"
  args:
    fields:
      lastViewed:
  register: issue

- name: Create a unix account for the reporter
  become: true
  user:
    name: '{{ issue.meta.fields.creator.name }}'
    comment: '{{ issue.meta.fields.creator.displayName }}'

# You can get list of valid linktypes at /rest/api/2/issueLinkType
# url of your jira installation.
- name: Create link from HSP-1 to MKY-1
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    operation: link
    linktype: Relates
    inwardissue: HSP-1
    outwardissue: MKY-1

# Transition an issue
- name: Resolve the issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: '{{ issue.meta.key }}'
    operation: transition
    status: Resolve Issue
    account_id: 112233445566778899aabbcc
    fields:
      resolution:
        name: Done
      description: I am done! This is the last description I will ever give you.

# Attach a file to an issue
- name: Attach a file
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    issue: HSP-1
    operation: attach
    attachment:
      filename: topsecretreport.xlsx

# Use username, password and client certificate authentification
- name: Create an issue
  community.general.jira:
    uri: '{{ server }}'
    username: '{{ user }}'
    password: '{{ pass }}'
    client_cert: '{{ path/to/client-cert }}'
    client_key: '{{ path/to/client-key }}'

# Use token and client certificate authentification
- name: Create an issue
  community.general.jira:
    uri: '{{ server }}'
    token: '{{ token }}'
    client_cert: '{{ path/to/client-cert }}'
    client_key: '{{ path/to/client-key }}'

Authors

• Steve Smith (@tarka)

• Per Abildgaard Toft (@pertoft)

• Brandon McNama (@DWSR)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication