github_key - Manage GitHub access keys.

New in version 2.2.


  • Creates, removes, or updates GitHub access keys.


parameter required default choices comments
no yes
  • yes
  • no
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.
SSH key name
no none
SSH public key value. Required when state=present.
no present
  • present
  • absent
Whether to remove a key, ensure that it exists, or update its value.
GitHub Access Token with permission to list and create public keys.


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

- name: Authorize key with GitHub
    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 Return Values, the following are the fields unique to this module:

name description returned type sample
matching_keys An array of keys matching the specified name. Only present on state=present When state=present list [{'url': ' key', 'read_only': False, 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key'}]
deleted_keys An array of key objects that were deleted. Only present on state=absent When state=absent list [{'url': ' key', 'read_only': False, 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key'}]
key Metadata about the key just created. Only present on state=present success dict {'url': ' key', 'read_only': False, 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'id': 0, 'key': 'BASE64 encoded key'}


This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.


This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.