ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-09 12:10:31 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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
parent eb2c3892ed
commit eafe80c924
No known key found for this signature in database
GPG key ID: 6A37FA54CFCFA4DB
2 changed files with 197 additions and 211 deletions
Show stats 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>
# 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)
# SPDX-License-Identifier: GPL-3.0-or-later
@ -13,10 +12,11 @@ __metaclass__ = type
DOCUMENTATION = '''
module: github_gpg_key
author: Austin Lucas Lake (@austinlucaslake)
short_description: Manage GitHub GPG keys
version_added: 9.0.0
description:
- Creates, removes, or list GitHub GPG keys.
- Creates or removes GitHub GPG keys for an authenticated user.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -42,7 +42,7 @@ options:
state:
description:
- Whether to remove a key, ensure that it exists, or update its value.
choices: ['present', 'absent']
choices: [ 'present', 'absent' ]
default: 'present'
type: str
force:
@ -52,8 +52,6 @@ options:
set if no key with the given O(name) exists.
type: bool
default: true
author: Austin Lucas Lake (@austinlucaslake)
'''
RETURN = '''
@ -63,140 +61,133 @@ deleted_keys:
elements: dict
returned: When O(state=absent)
sample: [{
"id": 3,
"name": "Octocat's GPG Key",
"primary_key_id": 2,
"key_id": "3262EFF25BA0D270",
"public_key": "xsBNBFayYZ...",
"emails": [{
"email": "octocat@users.noreply.github.com",
"verified": True
'id': 3,
'name': 'Octocat's GPG Key',
'primary_key_id': 2,
'key_id': '3262EFF25BA0D270',
'public_key': 'xsBNBFayYZ...',
'emails': [{
'email': 'octocat@users.noreply.github.com',
'verified': true
}],
"subkeys": [{
"id": 4,
"primary_key_id": 3,
"key_id": "4A595D4C72EE49C7",
"public_key": "zsBNBFayYZ...",
"emails": [],
"can_sign": False,
"can_encrypt_comms": true,
"can_encrypt_storage": True,
"can_certify": False,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False
'subkeys': [{
'id': 4,
'primary_key_id': 3,
'key_id': '4A595D4C72EE49C7',
'public_key': 'zsBNBFayYZ...',
'emails': [],
'can_sign': false,
'can_encrypt_comms': true,
'can_encrypt_storage': true,
'can_certify': false,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false
}],
"can_sign": True,
"can_encrypt_comms": False,
"can_encrypt_storage": False,
"can_certify": True,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False,
"raw_key": "string"
'can_sign': true,
'can_encrypt_comms': false,
'can_encrypt_storage': false,
'can_certify': true,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false,
'raw_key': 'string'
}]
matching_keys:
description: An array of keys matching the specified name. Only present on state=present
type: list
returned: When state=present
elements: dict
returned: When O(state=present)
sample: [{
"id": 3,
"name": "Octocat's GPG Key",
"primary_key_id": 2,
"key_id": "3262EFF25BA0D270",
"public_key": "xsBNBFayYZ...",
"emails": [{
"email": "octocat@users.noreply.github.com",
"verified": True
'id': 3,
'name': 'Octocat's GPG Key',
'primary_key_id': 2,
'key_id': '3262EFF25BA0D270',
'public_key': 'xsBNBFayYZ...',
'emails': [{
'email': 'octocat@users.noreply.github.com',
'verified': true
}],
"subkeys": [{
"id": 4,
"primary_key_id": 3,
"key_id": "4A595D4C72EE49C7",
"public_key": "zsBNBFayYZ...",
"emails": [],
"can_sign": False,
"can_encrypt_comms": True,
"can_encrypt_storage": True,
"can_certify": False,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False
'subkeys': [{
'id': 4,
'primary_key_id': 3,
'key_id': '4A595D4C72EE49C7',
'public_key': 'zsBNBFayYZ...',
'emails': [],
'can_sign': false,
'can_encrypt_comms': true,
'can_encrypt_storage': true,
'can_certify': false,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false
}],
"can_sign": True,
"can_encrypt_comms": False,
"can_encrypt_storage": False,
"can_certify": True,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False,
"raw_key": "string"
'can_sign': true,
'can_encrypt_comms': false,
'can_encrypt_storage': false,
'can_certify': true,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false,
'raw_key': 'string'
}]
key:
description: Metadata about the key just created. Only present on state=present
type: dict
returned: success
returned: When O(state=present)
sample: {
"id": 3,
"name": "Octocat's GPG Key",
"primary_key_id": 2,
"key_id": "3262EFF25BA0D270",
"public_key": "xsBNBFayYZ...",
"emails": [{
"email": "octocat@users.noreply.github.com",
"verified": True
'id': 3,
'name': 'Octocat's GPG Key',
'primary_key_id': 2,
'key_id': '3262EFF25BA0D270',
'public_key': 'xsBNBFayYZ...',
'emails': [{
'email': 'octocat@users.noreply.github.com',
'verified': true
}],
"subkeys": [{
"id": 4,
"primary_key_id": 3,
"key_id": "4A595D4C72EE49C7",
"public_key": "zsBNBFayYZ...",
"emails": [],
"can_sign": False,
"can_encrypt_comms": True,
"can_encrypt_storage": True,
"can_certify": False,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False
'subkeys': [{
'id': 4,
'primary_key_id': 3,
'key_id': '4A595D4C72EE49C7',
'public_key': 'zsBNBFayYZ...',
'emails': [],
'can_sign': false,
'can_encrypt_comms': true,
'can_encrypt_storage': true,
'can_certify': False,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false
}],
"can_sign": True,
"can_encrypt_comms": False,
"can_encrypt_storage": False,
"can_certify": True,
"created_at": "2016-03-24T11:31:04-06:00",
"expires_at": "2016-03-24T11:31:04-07:00",
"revoked": False,
"raw_key": "string"
'can_sign': true,
'can_encrypt_comms': false,
'can_encrypt_storage': false,
'can_certify': true,
'created_at': '2016-03-24T11:31:04-06:00',
'expires_at': '2016-03-24T11:31:04-07:00',
'revoked': false,
'raw_key': 'string'
}
'''
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
community.general.github_gpg_key:
name: Access Key for Some Machine
token: '{{ github_access_token }}'
armored_public_key: '{{ gpg_public_key.stdout }}'
name: My GPG Key
token: '{{ token }}'
armored_public_key: '{{ armored_public_key }}'
'''
import datetime
import json
import re
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url
from ansible_collections.community.general.plugins.module_utils.datetime import (
now,
)
from ansible_collections.community.general.plugins.module_utils.datetime import now
API_BASE = 'https://api.github.com'
API_BASE = 'https://api.github.com/user/gpg_keys'
class GitHubResponse(object):
@ -224,16 +215,14 @@ class GitHubSession(object):
def request(self, method, url, data=None):
headers = {
'Authorization': 'token %s' % self.token,
'Authorization': 'token {}'.format(self.token),
'Content-Type': 'application/json',
'Accept': 'application/vnd.github.v3+json'
}
response, info = fetch_url(
self.module, url, method=method, data=data, headers=headers)
if not (200 <= info['status'] < 400):
self.module.fail_json(
msg=(" failed to send request %s to %s: %s"
% (method, url, info['msg'])))
self.module.fail_json('failed to send request {0} to {1}: {2}'.format(method, url, info['msg']))
return GitHubResponse(response, info)
@ -249,44 +238,44 @@ def get_all_keys(session):
def create_key(session, name, armored_public_key, check_mode):
if check_mode:
now_t = datetime.datetime.now()
now_t = now()
return {
"id": 3,
"name": name,
"primary_key_id": 2,
"key_id": "3262EFF25BA0D270",
"public_key": "xsBNBFayYZ...",
"emails": [{
"email": "octocat@users.noreply.github.com",
"verified": True
'id': 3,
'name': name,
'primary_key_id': 2,
'key_id': '3262EFF25BA0D270',
'public_key': 'xsBNBFayYZ...',
'emails': [{
'email': 'octocat@users.noreply.github.com',
'verified': True
}],
"subkeys": [{
"id": 4,
"primary_key_id": 3,
"key_id": "4A595D4C72EE49C7",
"public_key": "zsBNBFayYZ...",
"emails": [],
"can_sign": False,
"can_encrypt_comms": True,
"can_encrypt_storage": True,
"can_certify": False,
"created_at": now_t.strftime("%Y-%m-%dT%H:%M:%SZ"),
"expires_at": None,
"revoked": False
'subkeys': [{
'id': 4,
'primary_key_id': 3,
'key_id': '4A595D4C72EE49C7',
'public_key': 'zsBNBFayYZ...',
'emails': [],
'can_sign': False,
'can_encrypt_comms': True,
'can_encrypt_storage': True,
'can_certify': False,
'created_at': now_t.strftime('%Y-%m-%dT%H:%M:%SZ'),
'expires_at': None,
'revoked': False
}],
"can_sign": True,
"can_encrypt_comms": False,
"can_encrypt_storage": False,
"can_certify": True,
"created_at": now_t.strftime("%Y-%m-%dT%H:%M:%SZ"),
"expires_at": None,
"revoked": False,
"raw_key": armored_public_key
'can_sign': True,
'can_encrypt_comms': False,
'can_encrypt_storage': False,
'can_certify': True,
'created_at': now_t.strftime('%Y-%m-%dT%H:%M:%SZ'),
'expires_at': None,
'revoked': False,
'raw_key': armored_public_key
}
else:
return session.request(
'POST',
API_BASE + '/user/gpg_keys',
API_BASE,
data=json.dumps({'name': name, 'raw_key': armored_public_key})).json()
@ -295,7 +284,7 @@ def delete_keys(session, to_delete, check_mode):
return
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):
@ -315,13 +304,11 @@ def ensure_key_present(module, session, name, armored_public_key, force, check_m
for key in all_keys:
existing_signature = key['raw_key']
if new_signature == existing_signature and key['name'] != name:
module.fail_json(msg=(
"another key with the same content is already registered "
"under the name |{0}|").format(key['title']))
module.fail_json('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:
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:
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):
session = GitHubSession(module, token)
if state == 'present':
ensure_key_present(module, session, name, armored_public_key, force=force,
check_mode=check_mode)
elif state == 'absent':
result = ensure_key_absent(session, name, check_mode=check_mode)
def validate_key(module, armored_public_key):
armored_public_key_parts = armored_public_key.splitlines()
if armored_public_key_parts[0] != '-----BEGIN PGP PUBLIC KEY BLOCK-----' or armored_public_key_parts[-1] != '-----END PGP PUBLIC KEY BLOCK-----':
module.fail_json(msg='"armored_public_key" parameter has an invalid format')
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
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(
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,
required_if=[
('state', 'present', ['armored_public_key']),
],
['state', 'present', ['armored_public_key']],
]
)
armored_public_key = module.params.get('armored_public_key')
if armored_public_key:
armored_public_key_parts = armored_public_key.split("\r\n")
armored_public_key_start = "-----BEGIN PGP PUBLIC KEY BLOCK-----"
armored_public_key_end = "-----END PGP PUBLIC KEY BLOCK-----"
if armored_public_key_parts[0] != armored_public_key_start or \
armored_public_key_parts[-1] != armored_public_key_end:
module.fail_json(msg='"armored_public_key" parameter has an invalid format')
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)
try:
result = run_module(
module=module,
params=module.params,
check_mode=module.check_mode
)
module.exit_json(**result)
except Exception as e:
module.fail_json(str(e))
if __name__ == "__main__":
if __name__ == '__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):
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(
argument_spec=argument_spec,
support_check_mode=True
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,
required_if=[
['state', 'present', ['armored_public_key']],
]
)
@with_httmock(list_gpg_keys_mock)
@ -139,11 +141,13 @@ class TestGithubRepo(unittest.TestCase):
def test_create_gpg_key_repo(self):
result = github_gpg_key.run_module(
module=self.module,
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="present",
force=True
params=dict(
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="present",
force=True
)
)
self.assertEqual(result['changed'], True)
self.assertEqual(result['key']['name'], 'GPG public key')
@ -153,11 +157,13 @@ class TestGithubRepo(unittest.TestCase):
def test_delete_user_repo(self):
result = github_gpg_key.run_module(
module=self.module
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="present",
force=True
params=dict(
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="absent",
force=True
)
)
self.assertEqual(result['changed'], True)
@ -166,11 +172,13 @@ class TestGithubRepo(unittest.TestCase):
def test_delete_gpg_key_notfound(self):
result = github_gpg_key.run_module(
module=self.module
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="present",
force=True
params=dict(
token="github_access_token",
name="GPG public key",
armored_public_key="-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\n\nMy ASCII-armored GPG public key\r\n-----END PGP PUBLIC KEY BLOCK-----",
state="absent",
force=True
)
)
self.assertEqual(result['changed'], False)