ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-05 18:20:30 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
community.general/plugins/modules/github_gpg_key.py
Austin Lucas Lake f62dc3b44f
updated tests
2025-03-15 12:51:01 -07:00

323 lines
9.4 KiB
Python
Raw Blame History

#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright (c) 2024-2025, Austin Lucas Lake <git@austinlucaslake.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
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
module: github_gpg_key
author: Austin Lucas Lake (@austinlucaslake)
short_description: Manage GitHub GPG keys
version_added: 10.5.0
description:
- Creates or removes GitHub GPG keys for an authenticated user.
extends_documentation_fragment:
- community.general.attributes
attributes:
check_mode:
support: full
diff_mode:
support: none
options:
token:
description:
- GitHub OAuth or personal access token (classic) with the C(read:gpg_key), C(write:gpg_key), and C(admin:gpg_key) scopes needed to manage GPG keys.
required: true
type: str
name:
description:
- GPG key name
type: str
armored_public_key:
description:
- ASCII-armored GPG public key value. Required when O(state=present).
type: str
gpg_key_id:
description:
- GPG key id. Required when O(state=absent).
type: int
state:
description:
- Whether to remove a key, ensure that it exists, or update its value.
choices: [ 'present', 'absent' ]
default: 'present'
type: str
'''
RETURN = '''
deleted_key:
description: A GPG key that was deleted from GitHub. Only present on O(state=absent).
type: list
elements: dict
returned: changed or success
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
}],
'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'
}
matching_key:
description: A matching GPG key found on GitHub. Only present when O(state=present) and no new key is created.
type: dict
returned: not changed
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
}],
'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'
}
new_key:
description: A new GPG key that was added to GitHub. Only present on O(state=present).
type: dict
returned: changed or success
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
}],
'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'
}
'''
EXAMPLES = '''
- name: Add GitHub GPG key
community.general.github_gpg_key:
state: present
token: '{{ token }}'
name: My GPG Key
armored_public_key: '{{ armored_public_key }}'
- name: Delete GitHub GPG key
community.general.github_gpg_key:
state: absent
token: '{{ token }}'
gpg_key_id: '{{ gpg_key_id }}'
'''
import json
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import open_url
GITHUB_GPG_REST_API_URL = 'https://api.github.com/user/gpg_keys'
def ensure_gpg_key_absent(headers, gpg_key_id, check_mode):
changed = False
deleted_key = {}
method = 'GET' if check_mode else 'DELETE'
response = open_url(
url=GITHUB_GPG_REST_API_URL + '/' + gpg_key_id,
method=method,
headers=headers
)
if (method == 'DELETE' and response.status == 204) \
or (method == 'GET' and response.status == 200):
changed = True
deleted_key = json.loads(response.read())
return {
'changed': changed,
'deleted_key': deleted_key
}
def ensure_gpg_key_present(headers, name, armored_public_key, check_mode):
changed = False
matching_key = {}
new_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-----'):
raise Exception('GPG key must have ASCII armor')
response = open_url(
url=GITHUB_GPG_REST_API_URL,
method='GET',
headers=headers
)
if response.status != 200:
raise Exception(
"Failed to check for matching GPG key: {} {}"
.format(response.status, response.reason)
)
keys = json.loads(response.read())
for key in keys:
if key['raw_key'] == armored_public_key:
matching_key = key
break
if not matching_key:
response = open_url(
url=GITHUB_GPG_REST_API_URL,
method='POST',
data={'name': name, 'armored_public_key': armored_public_key},
headers=headers
)
if response.status != 201:
raise Exception(
"Failed to create GPG key: {} {}"
.format(response.status, response.reason)
)
changed = True
new_key = json.loads(response.json())
if check_mode and new_key:
response = open_url(
url=GITHUB_GPG_REST_API_URL + '/' + new_key['id'],
method='DELETE',
headers=headers
)
if response.status != 200:
raise Exception(
"Failed to undo changes (check_mode=true): {} {}"
.format(response.status, response.reason)
)
return {
'changed': changed,
'matching_key': matching_key,
'new_key': new_key
}
def run_module(params, check_mode):
headers = {
'Accept': 'application/vnd.github+json',
'Authorization': 'Bearer {}'.format(params['token']),
'X-GitHub-Api-Version': '2022-11-28',
}
if params['state'] == 'present':
result = ensure_gpg_key_present(
headers,
params['name'],
params['armored_public_key'],
check_mode
)
else:
result = ensure_gpg_key_absent(
headers,
params['gpg_key_id'],
check_mode
)
return result
def main():
module = AnsibleModule(
argument_spec=dict(
state=dict(type='str', default='present', choices=['present', 'absent']),
token=dict(type='str', required=True, no_log=True),
name=dict(type='str', no_log=True),
armored_public_key=dict(type='str', no_log=True),
gpg_key_id=dict(type='int', no_log=True)
),
supports_check_mode=True,
required_if=[
['state', 'present', ['armored_public_key']],
['state', 'absent', ['gpg_key_id']],
]
)
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(msg=str(e))
if __name__ == '__main__':
main()
Reference in a new issue View git blame Copy permalink