# github_key – Manage GitHub access keys

- Synopsis
- Parameters
- Examples
- Return Values
- Status

## 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 - / required |  | SSH key name
pubkey - |  | SSH public key value. Required when `state=present`.

state
-

Choices:
- present ←
- absent

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

token - / required |  | GitHub Access Token with permission to list and create public keys.

## Examples

    - name: Read SSH public key to authorize
      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 | When state=absent | An array of key objects that were deleted. Only present on state=absent Sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': False}]
key dictionary | success | Metadata about the key just created. Only present on state=present Sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': False}
matching_keys list | When state=present | An array of keys matching the specified name. Only present on state=present Sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': False}]

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Robert Estelle (@erydo)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.