community.general.github_key module – Manage GitHub access keys

Note

This module is part of the community.general collection (version 5.8.3).

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

Comments

force

boolean

The default is true, which will replace the existing remote key if it’s different than pubkey. If false, the key will only be set if no key with the given name exists.

Choices:

  • false

  • true ← (default)

name

string / required

SSH key name

pubkey

string

SSH public key value. Required when state=present.

state

string

Whether to remove a key, ensure that it exists, or update its value.

Choices:

  • "present" ← (default)

  • "absent"

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

Description

deleted_keys

list / elements=string

An array of key objects that were deleted. Only present on state=absent

Returned: When 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

Metadata about the key just created. Only present on state=present

Returned: success

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

An array of keys matching the specified name. Only present on state=present

Returned: When 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)