community.general.github_key module – Manage GitHub access keys

Note

This module is part of the community.general collection (version 11.2.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.

  • Works with both GitHub.com and GitHub Enterprise Server installations.

Parameters

Parameter

Comments

api_url

string

added in community.general 11.0.0

URL to the GitHub API if not using github.com but your own GitHub Enterprise instance.

Default: "https://api.github.com"

force

boolean

The default is true, which replaces the existing remote key if it is different than pubkey. If false, the key is only 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

Returns 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') }}"

# GitHub Enterprise Server usage
- name: Authorize key with GitHub Enterprise
  community.general.github_key:
    name: Access Key for Some Machine
    token: '{{ github_enterprise_token }}'
    pubkey: "{{ lookup('ansible.builtin.file', '/home/foo/.ssh/id_rsa.pub') }}"
    api_url: 'https://github.company.com/api/v3'

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)