ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-30 00:21:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

updated documentation and unit testing

Browse source
This commit is contained in:
Austin Lucas Lake 2024-05-09 23:58:11 -07:00 • committed by Austin Lucas Lake
commit eafe80c924
No known key found for this signature in database
GPG key ID: 6A37FA54CFCFA4DB
2 changed files with 197 additions and 211 deletions
Download patch file Download diff file Expand all files Collapse all files

352
plugins/modules/github_gpg_key.py
View file

@ -3,7 +3,6 @@
# Copyright 2024, Austin Lucas Lake <53884490+austinlucaslake@users.noreply.github.com> # Copyright 2024, Austin Lucas Lake <53884490+austinlucaslake@users.noreply.github.com>
# Based on community.general.github_key module by Ansible Project # Based on community.general.github_key module by Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later # SPDX-License-Identifier: GPL-3.0-or-later
@ -13,10 +12,11 @@ __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = '''
module: github_gpg_key module: github_gpg_key
author: Austin Lucas Lake (@austinlucaslake)
short_description: Manage GitHub GPG keys short_description: Manage GitHub GPG keys
version_added: 9.0.0 version_added: 9.0.0
description: description:
- Creates, removes, or list GitHub GPG keys. - Creates or removes GitHub GPG keys for an authenticated user.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -42,7 +42,7 @@ options:
state: state:
description: description:
- Whether to remove a key, ensure that it exists, or update its value. - Whether to remove a key, ensure that it exists, or update its value.
choices: ['present', 'absent'] choices: [ 'present', 'absent' ]
default: 'present' default: 'present'
type: str type: str
force: force:
@ -52,8 +52,6 @@ options:
set if no key with the given O(name) exists. set if no key with the given O(name) exists.
type: bool type: bool
default: true default: true
author: Austin Lucas Lake (@austinlucaslake)
''' '''
RETURN = ''' RETURN = '''
@ -63,140 +61,133 @@ deleted_keys:
elements: dict elements: dict
returned: When O(state=absent) returned: When O(state=absent)
sample: [{ sample: [{
"id": 3, 'id': 3,
"name": "Octocat's GPG Key", 'name': 'Octocat's GPG Key',
"primary_key_id": 2, 'primary_key_id': 2,
"key_id": "3262EFF25BA0D270", 'key_id': '3262EFF25BA0D270',
"public_key": "xsBNBFayYZ...", 'public_key': 'xsBNBFayYZ...',
"emails": [{ 'emails': [{
"email": "octocat@users.noreply.github.com", 'email': 'octocat@users.noreply.github.com',
"verified": True 'verified': true
}], }],
"subkeys": [{ 'subkeys': [{
"id": 4, 'id': 4,
"primary_key_id": 3, 'primary_key_id': 3,
"key_id": "4A595D4C72EE49C7", 'key_id': '4A595D4C72EE49C7',
"public_key": "zsBNBFayYZ...", 'public_key': 'zsBNBFayYZ...',
"emails": [], 'emails': [],
"can_sign": False, 'can_sign': false,
"can_encrypt_comms": true, 'can_encrypt_comms': true,
"can_encrypt_storage": True, 'can_encrypt_storage': true,
"can_certify": False, 'can_certify': false,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False 'revoked': false
}], }],
"can_sign": True, 'can_sign': true,
"can_encrypt_comms": False, 'can_encrypt_comms': false,
"can_encrypt_storage": False, 'can_encrypt_storage': false,
"can_certify": True, 'can_certify': true,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False, 'revoked': false,
"raw_key": "string" 'raw_key': 'string'
}] }]
matching_keys: matching_keys:
description: An array of keys matching the specified name. Only present on state=present description: An array of keys matching the specified name. Only present on state=present
type: list type: list
returned: When state=present elements: dict
returned: When O(state=present)
sample: [{ sample: [{
"id": 3, 'id': 3,
"name": "Octocat's GPG Key", 'name': 'Octocat's GPG Key',
"primary_key_id": 2, 'primary_key_id': 2,
"key_id": "3262EFF25BA0D270", 'key_id': '3262EFF25BA0D270',
"public_key": "xsBNBFayYZ...", 'public_key': 'xsBNBFayYZ...',
"emails": [{ 'emails': [{
"email": "octocat@users.noreply.github.com", 'email': 'octocat@users.noreply.github.com',
"verified": True 'verified': true
}], }],
"subkeys": [{ 'subkeys': [{
"id": 4, 'id': 4,
"primary_key_id": 3, 'primary_key_id': 3,
"key_id": "4A595D4C72EE49C7", 'key_id': '4A595D4C72EE49C7',
"public_key": "zsBNBFayYZ...", 'public_key': 'zsBNBFayYZ...',
"emails": [], 'emails': [],
"can_sign": False, 'can_sign': false,
"can_encrypt_comms": True, 'can_encrypt_comms': true,
"can_encrypt_storage": True, 'can_encrypt_storage': true,
"can_certify": False, 'can_certify': false,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False 'revoked': false
}], }],
"can_sign": True, 'can_sign': true,
"can_encrypt_comms": False, 'can_encrypt_comms': false,
"can_encrypt_storage": False, 'can_encrypt_storage': false,
"can_certify": True, 'can_certify': true,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False, 'revoked': false,
"raw_key": "string" 'raw_key': 'string'
}] }]
key: key:
description: Metadata about the key just created. Only present on state=present description: Metadata about the key just created. Only present on state=present
type: dict type: dict
returned: success returned: When O(state=present)
sample: { sample: {
"id": 3, 'id': 3,
"name": "Octocat's GPG Key", 'name': 'Octocat's GPG Key',
"primary_key_id": 2, 'primary_key_id': 2,
"key_id": "3262EFF25BA0D270", 'key_id': '3262EFF25BA0D270',
"public_key": "xsBNBFayYZ...", 'public_key': 'xsBNBFayYZ...',
"emails": [{ 'emails': [{
"email": "octocat@users.noreply.github.com", 'email': 'octocat@users.noreply.github.com',
"verified": True 'verified': true
}], }],
"subkeys": [{ 'subkeys': [{
"id": 4, 'id': 4,
"primary_key_id": 3, 'primary_key_id': 3,
"key_id": "4A595D4C72EE49C7", 'key_id': '4A595D4C72EE49C7',
"public_key": "zsBNBFayYZ...", 'public_key': 'zsBNBFayYZ...',
"emails": [], 'emails': [],
"can_sign": False, 'can_sign': false,
"can_encrypt_comms": True, 'can_encrypt_comms': true,
"can_encrypt_storage": True, 'can_encrypt_storage': true,
"can_certify": False, 'can_certify': False,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False 'revoked': false
}], }],
"can_sign": True, 'can_sign': true,
"can_encrypt_comms": False, 'can_encrypt_comms': false,
"can_encrypt_storage": False, 'can_encrypt_storage': false,
"can_certify": True, 'can_certify': true,
"created_at": "2016-03-24T11:31:04-06:00", 'created_at': '2016-03-24T11:31:04-06:00',
"expires_at": "2016-03-24T11:31:04-07:00", 'expires_at': '2016-03-24T11:31:04-07:00',
"revoked": False, 'revoked': false,
"raw_key": "string" 'raw_key': 'string'
} }
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: Read ASCII-armored GPG public key to authorize
ansible.builtin.command:
cmd: gpg --armor --export EXAMPLE_KEY_ID
register: gpg_public_key
- name: Authorize key with GitHub - name: Authorize key with GitHub
community.general.github_gpg_key: community.general.github_gpg_key:
name: Access Key for Some Machine name: My GPG Key
token: '{{ github_access_token }}' token: '{{ token }}'
armored_public_key: '{{ gpg_public_key.stdout }}' armored_public_key: '{{ armored_public_key }}'
''' '''
import datetime
import json import json
import re import re
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url from ansible.module_utils.urls import fetch_url
from ansible_collections.community.general.plugins.module_utils.datetime import ( from ansible_collections.community.general.plugins.module_utils.datetime import now
now,
)
API_BASE = 'https://api.github.com' API_BASE = 'https://api.github.com/user/gpg_keys'
class GitHubResponse(object): class GitHubResponse(object):
@ -224,16 +215,14 @@ class GitHubSession(object):
def request(self, method, url, data=None): def request(self, method, url, data=None):
headers = { headers = {
'Authorization': 'token %s' % self.token, 'Authorization': 'token {}'.format(self.token),
'Content-Type': 'application/json', 'Content-Type': 'application/json',
'Accept': 'application/vnd.github.v3+json' 'Accept': 'application/vnd.github.v3+json'
} }
response, info = fetch_url( response, info = fetch_url(
self.module, url, method=method, data=data, headers=headers) self.module, url, method=method, data=data, headers=headers)
if not (200 <= info['status'] < 400): if not (200 <= info['status'] < 400):
self.module.fail_json( self.module.fail_json('failed to send request {0} to {1}: {2}'.format(method, url, info['msg']))
msg=(" failed to send request %s to %s: %s"
% (method, url, info['msg'])))
return GitHubResponse(response, info) return GitHubResponse(response, info)
@ -249,44 +238,44 @@ def get_all_keys(session):
def create_key(session, name, armored_public_key, check_mode): def create_key(session, name, armored_public_key, check_mode):
if check_mode: if check_mode:
now_t = datetime.datetime.now() now_t = now()
return { return {
"id": 3, 'id': 3,
"name": name, 'name': name,
"primary_key_id": 2, 'primary_key_id': 2,
"key_id": "3262EFF25BA0D270", 'key_id': '3262EFF25BA0D270',
"public_key": "xsBNBFayYZ...", 'public_key': 'xsBNBFayYZ...',
"emails": [{ 'emails': [{
"email": "octocat@users.noreply.github.com", 'email': 'octocat@users.noreply.github.com',
"verified": True 'verified': True
}], }],
"subkeys": [{ 'subkeys': [{
"id": 4, 'id': 4,
"primary_key_id": 3, 'primary_key_id': 3,
"key_id": "4A595D4C72EE49C7", 'key_id': '4A595D4C72EE49C7',
"public_key": "zsBNBFayYZ...", 'public_key': 'zsBNBFayYZ...',
"emails": [], 'emails': [],
"can_sign": False, 'can_sign': False,
"can_encrypt_comms": True, 'can_encrypt_comms': True,
"can_encrypt_storage": True, 'can_encrypt_storage': True,
"can_certify": False, 'can_certify': False,
"created_at": now_t.strftime("%Y-%m-%dT%H:%M:%SZ"), 'created_at': now_t.strftime('%Y-%m-%dT%H:%M:%SZ'),
"expires_at": None, 'expires_at': None,
"revoked": False 'revoked': False
}], }],
"can_sign": True, 'can_sign': True,
"can_encrypt_comms": False, 'can_encrypt_comms': False,
"can_encrypt_storage": False, 'can_encrypt_storage': False,
"can_certify": True, 'can_certify': True,
"created_at": now_t.strftime("%Y-%m-%dT%H:%M:%SZ"), 'created_at': now_t.strftime('%Y-%m-%dT%H:%M:%SZ'),
"expires_at": None, 'expires_at': None,
"revoked": False, 'revoked': False,
"raw_key": armored_public_key 'raw_key': armored_public_key
} }
else: else:
return session.request( return session.request(
'POST', 'POST',
API_BASE + '/user/gpg_keys', API_BASE,
data=json.dumps({'name': name, 'raw_key': armored_public_key})).json() data=json.dumps({'name': name, 'raw_key': armored_public_key})).json()
@ -295,7 +284,7 @@ def delete_keys(session, to_delete, check_mode):
return return
for key in to_delete: for key in to_delete:
session.request('DELETE', API_BASE + '/user/keys/%s' % key["id"]) session.request('DELETE', API_BASE + '/' + key['id'])
def ensure_key_absent(session, name, check_mode): def ensure_key_absent(session, name, check_mode):
@ -315,13 +304,11 @@ def ensure_key_present(module, session, name, armored_public_key, force, check_m
for key in all_keys: for key in all_keys:
existing_signature = key['raw_key'] existing_signature = key['raw_key']
if new_signature == existing_signature and key['name'] != name: if new_signature == existing_signature and key['name'] != name:
module.fail_json(msg=( module.fail_json('Another key with the same content is already registered under the name |{0}|'.format(key['title']))
"another key with the same content is already registered "
"under the name |{0}|").format(key['title']))
if matching_keys and force and matching_keys[0]['raw_key'] != new_signature: if matching_keys and force and matching_keys[0]['raw_key'] != new_signature:
delete_keys(session, matching_keys, check_mode=check_mode) delete_keys(session, matching_keys, check_mode=check_mode)
(deleted_keys, matching_keys) = (matching_keys, []) deleted_keys, matching_keys = matching_keys, []
if not matching_keys: if not matching_keys:
key = create_key(session, name, armored_public_key, check_mode=check_mode) key = create_key(session, name, armored_public_key, check_mode=check_mode)
@ -336,56 +323,47 @@ def ensure_key_present(module, session, name, armored_public_key, force, check_m
} }
def run_module(module, token, name, armored_public_key, state, force, check_mode): def validate_key(module, armored_public_key):
session = GitHubSession(module, token) armored_public_key_parts = armored_public_key.splitlines()
if state == 'present': if armored_public_key_parts[0] != '-----BEGIN PGP PUBLIC KEY BLOCK-----' or armored_public_key_parts[-1] != '-----END PGP PUBLIC KEY BLOCK-----':
ensure_key_present(module, session, name, armored_public_key, force=force, module.fail_json(msg='"armored_public_key" parameter has an invalid format')
check_mode=check_mode)
elif state == 'absent':
result = ensure_key_absent(session, name, check_mode=check_mode)
def run_module(module, params, check_mode):
session = GitHubSession(module, params['token'])
if params['state'] == 'present':
validate_key(module, params['armored_public_key'])
result = ensure_key_present(module, session, params['name'], params['armored_public_key'], params['force'], check_mode)
else:
result = ensure_key_absent(session, params['name'], check_mode)
return result return result
def main(): def main():
argument_spec = {
'token': {'required': True, 'no_log': True},
'name': {'required': True},
'armored_public_key': {},
'state': {'choices': ['present', 'absent'], 'default': 'present'},
'force': {'default': True, 'type': 'bool'},
}
module = AnsibleModule( module = AnsibleModule(
argument_spec=argument_spec, argument_spec=dict(
state=dict(type='str', default='present', choice=['present', 'absent']),
token=dict(type='str', required=True, no_log=True),
name=dict(type='str', required=True),
armored_public_key=dict(type='str', no_log=True),
force=dict(type='bool', default=True)
),
supports_check_mode=True, supports_check_mode=True,
required_if=[ required_if=[
('state', 'present', ['armored_public_key']), ['state', 'present', ['armored_public_key']],
], ]
) )
armored_public_key = module.params.get('armored_public_key') try:
result = run_module(
if armored_public_key: module=module,
armored_public_key_parts = armored_public_key.split("\r\n") params=module.params,
armored_public_key_start = "-----BEGIN PGP PUBLIC KEY BLOCK-----" check_mode=module.check_mode
armored_public_key_end = "-----END PGP PUBLIC KEY BLOCK-----" )
if armored_public_key_parts[0] != armored_public_key_start or \ module.exit_json(**result)
armored_public_key_parts[-1] != armored_public_key_end: except Exception as e:
module.fail_json(msg='"armored_public_key" parameter has an invalid format') module.fail_json(str(e))
elif state == "present":
module.fail_json(msg='"armored_public_key" is required when state=present')
result = run_module(
module=module,
token=module.params["token"],
name=module.params["name"],
armored_public_key=armored_public_key,
state=module.params["state"],
force=module.params["force"],
check_mode=check_mode
)
module.exit_json(**result)
if __name__ == "__main__": if __name__ == '__main__':
main() main()

56
tests/unit/plugins/modules/test_github_gpg_key.py
View file

@ -122,16 +122,18 @@ def delete_gpg_key_notfound_mock(url, request):
class TestGithubRepo(unittest.TestCase): class TestGithubRepo(unittest.TestCase):
def setUp(self): def setUp(self):
argument_spec = {
'token': {'required': True, 'no_log': True},
'name': {'required': True},
'armored_public_key': {},
'state': {'choices': ['present', 'absent'], 'default': 'present'},
'force': {'default': True, 'type': 'bool'}
}
self.module = AnsibleModule( self.module = AnsibleModule(
argument_spec=argument_spec, argument_spec=dict(
support_check_mode=True state=dict(type='str', default='present', choice=['present', 'absent']),
token=dict(type='str', required=True, no_log=True),
name=dict(type='str', required=True),
armored_public_key=dict(type='str', no_log=True),
force=dict(type='bool', default=True)
),
supports_check_mode=True,
required_if=[
['state', 'present', ['armored_public_key']],
]
) )
@with_httmock(list_gpg_keys_mock) @with_httmock(list_gpg_keys_mock)
@ -139,11 +141,13 @@ class TestGithubRepo(unittest.TestCase):
def test_create_gpg_key_repo(self): def test_create_gpg_key_repo(self):
result = github_gpg_key.run_module( result = github_gpg_key.run_module(
module=self.module, module=self.module,
token="github_access_token", params=dict(
name="GPG public key", token="github_access_token",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----", name="GPG public key",
state="present", armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
force=True state="present",
force=True
)
) )
self.assertEqual(result['changed'], True) self.assertEqual(result['changed'], True)
self.assertEqual(result['key']['name'], 'GPG public key') self.assertEqual(result['key']['name'], 'GPG public key')
@ -153,11 +157,13 @@ class TestGithubRepo(unittest.TestCase):
def test_delete_user_repo(self): def test_delete_user_repo(self):
result = github_gpg_key.run_module( result = github_gpg_key.run_module(
module=self.module module=self.module
token="github_access_token", params=dict(
name="GPG public key", token="github_access_token",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----", name="GPG public key",
state="present", armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
force=True state="absent",
force=True
)
) )
self.assertEqual(result['changed'], True) self.assertEqual(result['changed'], True)
@ -166,11 +172,13 @@ class TestGithubRepo(unittest.TestCase):
def test_delete_gpg_key_notfound(self): def test_delete_gpg_key_notfound(self):
result = github_gpg_key.run_module( result = github_gpg_key.run_module(
module=self.module module=self.module
token="github_access_token", params=dict(
name="GPG public key", token="github_access_token",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----", name="GPG public key",
state="present", armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
force=True state="absent",
force=True
)
) )
self.assertEqual(result['changed'], False) self.assertEqual(result['changed'], False)