github_deploy_key - Manages deploy keys for GitHub repositories.

New in version 2.4.

Synopsis

  • Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password, username and password and 2-factor authentication code (OTP), OAuth2 token, or personal access token.

Requirements

The below requirements are needed on the host that executes this module.

  • python-requests

Parameters

Parameter Choices/Defaults Comments
force
    Choices:
  • no
  • yes
If true, forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.
key
required
Default:
None
The SSH public key to add to the repository as a deploy key.
name
required
Default:
None
The name for the deploy key.

aliases: title, label
otp Default:
None
The 6 digit One Time Password for 2-Factor Authentication. Required together with username and password.

aliases: 2fa_token
owner
required
Default:
None
The name of the individual account or organization that owns the GitHub repository.

aliases: account, organization
password Default:
None
The password to authenticate with. A personal access token can be used here in place of a password.
read_only
    Choices:
  • no
  • yes
If true, the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
repo
required
Default:
None
The name of the GitHub repository.

aliases: repository
state
    Choices:
  • present
  • absent
The state of the deploy key.
token Default:
None
The OAuth2 token or personal access token to authenticate with. Mutually exclusive with password.
username Default:
None
The username to authenticate with.

Notes

Note

Examples

# add a new read-only deploy key to a GitHub repository using basic authentication
- github_deploy_key:
    owner: "johndoe"
    repo: "example"
    name: "new-deploy-key"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    read_only: yes
    username: "johndoe"
    password: "supersecretpassword"

# remove an existing deploy key from a GitHub repository
- github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "new-deploy-key"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    force: yes
    username: "johndoe"
    password: "supersecretpassword"
    state: absent

# add a new deploy key to a GitHub repository, replace an existing key, use an OAuth2 token to authenticate
- github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "new-deploy-key"
    key: "{{ lookup('file', '~/.ssh/github.pub') }}"
    force: yes
    token: "ABAQDAwXxn7kIMNWzcDfo..."

# re-add a deploy key to a GitHub repository but with a different name
- github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "replace-deploy-key"
    key: "{{ lookup('file', '~/.ssh/github.pub') }}"
    username: "johndoe"
    password: "supersecretpassword"

# add a new deploy key to a GitHub repository using 2FA
- github_deploy_key:
    owner: "johndoe"
    repo: "example"
    name: "new-deploy-key-2"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    username: "johndoe"
    password: "supersecretpassword"
    otp: 123456

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
error
string
failed
the error message returned by the GitHub API

Sample:
key is already in use
http_status_code
int
failed
the HTTP status code returned by the GitHub API

Sample:
400
id
int
changed
the key identifier assigned by GitHub for the deploy key

Sample:
24381901
msg
string
always
the status message describing what occurred

Sample:
Deploy key added successfully


Status

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

Author

  • Ali (@bincyber)

Hint

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

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/github_deploy_key_module.html