1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
community.general/plugins/modules/web_infrastructure/jira.py

444 lines
11 KiB
Python
Raw Normal View History

2020-03-09 10:11:07 +01:00
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2014, Steve Smith <ssmith@atlassian.com>
# Atlassian open-source approval reference OSR-76.
#
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
module: jira
short_description: create and modify issues in a JIRA instance
description:
- Create and modify issues in a JIRA instance.
options:
uri:
required: true
description:
- Base URI for the JIRA instance.
operation:
required: true
aliases: [ command ]
choices: [ create, comment, edit, fetch, transition , link ]
description:
- The operation to perform.
username:
required: true
description:
- The username to log-in with.
password:
required: true
description:
- The password to log-in with.
project:
required: false
description:
- The project for this operation. Required for issue creation.
summary:
required: false
description:
- The issue summary, where appropriate.
description:
required: false
description:
- The issue description, where appropriate.
issuetype:
required: false
description:
- The issue type, for issue creation.
issue:
required: false
description:
- An existing issue key to operate on.
comment:
required: false
description:
- The comment text to add.
status:
required: false
description:
- The desired status; only relevant for the transition operation.
assignee:
required: false
description:
- Sets the assignee on create or transition operations. Note not all transitions will allow this.
linktype:
required: false
description:
- Set type of link, when action 'link' selected.
inwardissue:
required: false
description:
- Set issue from which link will be created.
outwardissue:
required: false
description:
- Set issue to which link will be created.
fields:
required: false
description:
- 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.
timeout:
required: false
description:
- Set timeout, in seconds, on requests to JIRA API.
default: 10
validate_certs:
required: false
description:
- Require valid SSL certificates (set to `false` if you'd like to use self-signed certificates)
default: true
type: bool
notes:
- "Currently this only works with basic-auth."
author: "Steve Smith (@tarka)"
'''
EXAMPLES = """
# Create a new issue and add a comment to it:
- name: Create an issue
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
project: ANS
operation: create
summary: Example Issue
description: Created using Ansible
issuetype: Task
register: issue
- name: Comment on issue
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
issue: '{{ issue.meta.key }}'
operation: comment
comment: A comment added by Ansible
# Assign an existing issue using edit
- name: Assign an issue using free-form fields
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
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
project: ANS
operation: create
summary: Assigned issue
description: Created and assigned using Ansible
issuetype: Task
assignee: ssmith
# Edit an issue
- name: Set the labels on an issue using free-form fields
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
issue: '{{ issue.meta.key }}'
operation: edit
args:
fields:
labels:
- autocreated
- ansible
# Retrieve metadata for an issue and use it to create an account
- name: Get an issue
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
project: ANS
operation: fetch
issue: ANS-63
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
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
operation: link
linktype: Relates
inwardissue: HSP-1
outwardissue: MKY-1
# Transition an issue by target status
- name: Close the issue
jira:
uri: '{{ server }}'
username: '{{ user }}'
password: '{{ pass }}'
issue: '{{ issue.meta.key }}'
operation: transition
status: Done
"""
import base64
import json
import sys
from ansible.module_utils._text import to_text, to_bytes
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
def request(url, user, passwd, timeout, data=None, method=None):
if data:
data = json.dumps(data)
# NOTE: fetch_url uses a password manager, which follows the
# standard request-then-challenge basic-auth semantics. However as
# JIRA allows some unauthorised operations it doesn't necessarily
# send the challenge, so the request occurs as the anonymous user,
# resulting in unexpected results. To work around this we manually
# inject the basic-auth header up-front to ensure that JIRA treats
# the requests as authorized for this user.
auth = to_text(base64.b64encode(to_bytes('{0}:{1}'.format(user, passwd), errors='surrogate_or_strict')))
response, info = fetch_url(module, url, data=data, method=method, timeout=timeout,
headers={'Content-Type': 'application/json',
'Authorization': "Basic %s" % auth})
if info['status'] not in (200, 201, 204):
module.fail_json(msg=info['msg'])
body = response.read()
if body:
return json.loads(to_text(body, errors='surrogate_or_strict'))
else:
return {}
def post(url, user, passwd, timeout, data):
return request(url, user, passwd, timeout, data=data, method='POST')
def put(url, user, passwd, timeout, data):
return request(url, user, passwd, timeout, data=data, method='PUT')
def get(url, user, passwd, timeout):
return request(url, user, passwd, timeout)
def create(restbase, user, passwd, params):
createfields = {
'project': {'key': params['project']},
'summary': params['summary'],
'issuetype': {'name': params['issuetype']}}
if params['description']:
createfields['description'] = params['description']
# Merge in any additional or overridden fields
if params['fields']:
createfields.update(params['fields'])
data = {'fields': createfields}
url = restbase + '/issue/'
ret = post(url, user, passwd, params['timeout'], data)
return ret
def comment(restbase, user, passwd, params):
data = {
'body': params['comment']
}
url = restbase + '/issue/' + params['issue'] + '/comment'
ret = post(url, user, passwd, params['timeout'], data)
return ret
def edit(restbase, user, passwd, params):
data = {
'fields': params['fields']
}
url = restbase + '/issue/' + params['issue']
ret = put(url, user, passwd, params['timeout'], data)
return ret
def fetch(restbase, user, passwd, params):
url = restbase + '/issue/' + params['issue']
ret = get(url, user, passwd, params['timeout'])
return ret
def transition(restbase, user, passwd, params):
# Find the transition id
turl = restbase + '/issue/' + params['issue'] + "/transitions"
tmeta = get(turl, user, passwd, params['timeout'])
target = params['status']
tid = None
for t in tmeta['transitions']:
if t['name'] == target:
tid = t['id']
break
if not tid:
raise ValueError("Failed find valid transition for '%s'" % target)
# Perform it
url = restbase + '/issue/' + params['issue'] + "/transitions"
data = {'transition': {"id": tid},
'fields': params['fields']}
ret = post(url, user, passwd, params['timeout'], data)
return ret
def link(restbase, user, passwd, params):
data = {
'type': {'name': params['linktype']},
'inwardIssue': {'key': params['inwardissue']},
'outwardIssue': {'key': params['outwardissue']},
}
url = restbase + '/issueLink/'
ret = post(url, user, passwd, params['timeout'], data)
return ret
# Some parameters are required depending on the operation:
OP_REQUIRED = dict(create=['project', 'issuetype', 'summary'],
comment=['issue', 'comment'],
edit=[],
fetch=['issue'],
transition=['status'],
link=['linktype', 'inwardissue', 'outwardissue'])
def main():
global module
module = AnsibleModule(
argument_spec=dict(
uri=dict(required=True),
operation=dict(choices=['create', 'comment', 'edit', 'fetch', 'transition', 'link'],
aliases=['command'], required=True),
username=dict(required=True),
password=dict(required=True, no_log=True),
project=dict(),
summary=dict(),
description=dict(),
issuetype=dict(),
issue=dict(aliases=['ticket']),
comment=dict(),
status=dict(),
assignee=dict(),
fields=dict(default={}, type='dict'),
linktype=dict(),
inwardissue=dict(),
outwardissue=dict(),
timeout=dict(type='float', default=10),
validate_certs=dict(default=True, type='bool'),
),
supports_check_mode=False
)
op = module.params['operation']
# Check we have the necessary per-operation parameters
missing = []
for parm in OP_REQUIRED[op]:
if not module.params[parm]:
missing.append(parm)
if missing:
module.fail_json(msg="Operation %s require the following missing parameters: %s" % (op, ",".join(missing)))
# Handle rest of parameters
uri = module.params['uri']
user = module.params['username']
passwd = module.params['password']
if module.params['assignee']:
module.params['fields']['assignee'] = {'name': module.params['assignee']}
if not uri.endswith('/'):
uri = uri + '/'
restbase = uri + 'rest/api/2'
# Dispatch
try:
# Lookup the corresponding method for this operation. This is
# safe as the AnsibleModule should remove any unknown operations.
thismod = sys.modules[__name__]
method = getattr(thismod, op)
ret = method(restbase, user, passwd, module.params)
except Exception as e:
return module.fail_json(msg=e.message)
module.exit_json(changed=True, meta=ret)
if __name__ == '__main__':
main()