community.general.github_key module – Manage GitHub access keys

Note

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

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 is 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.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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 }}'

# Alternatively, a single task can be used reading a key from a file on the controller
- name: Authorize key with GitHub
  community.general.github_key:
    name: Access Key for Some Machine
    token: '{{ github_access_token }}'
    pubkey: "{{ lookup('ansible.builtin.file', '/home/foo/.ssh/id_rsa.pub') }}"

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)