Docs4dev
Docs
ansible / latest / collections / community / general / github_key_module.html

community.general.github_key – Manage GitHub access keys.

Note

This plugin is part of the community.general collection (version 3.8.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.github_key.

Synopsis

  • Creates, removes, or updates GitHub access keys.

Parameters

Parameter Choices/Defaults Comments
force
boolean
    Choices:
  • no
  • yes ←
The default is yes, which will replace the existing remote key if it's different than pubkey. If no, the key will only be set if no key with the given name exists.
name
string / required
SSH key name
pubkey
string
SSH public key value. Required when state=present.
state
string
    Choices:
  • present ←
  • absent
Whether to remove a key, ensure that it exists, or update its value.
token
string / required
GitHub Access Token with permission to list and create public keys.

Examples

- name: Read SSH public key to authorize
  ansible.builtin.shell: cat /home/foo/.ssh/id_rsa.pub
  register: ssh_pub_key

- name: Authorize key with GitHub
  local_action:
    module: github_key
    name: Access Key for Some Machine
    token: '{{ github_access_token }}'
    pubkey: '{{ ssh_pub_key.stdout }}'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
deleted_keys
list / elements=string
When state=absent
An array of key objects that were deleted. Only present on state=absent

Sample:
[{'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key', 'read_only': False, 'url': 'http://example.com/github key'}]
key
dictionary
success
Metadata about the key just created. Only present on state=present

Sample:
{'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key', 'read_only': False, 'url': 'http://example.com/github key'}
matching_keys
list / elements=string
When state=present
An array of keys matching the specified name. Only present on state=present

Sample:
[{'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key', 'read_only': False, 'url': 'http://example.com/github key'}]


Authors

  • Robert Estelle (@erydo)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/github_key_module.html