Docs4dev
Docs
ansible / 2.4 / github_deploy_key_module.html

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 (on host that executes module)

  • python-requests

Options

parameter required default choices comments
force
 no
  • yes
  • no
If true, forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.
key
 yes
The SSH public key to add to the repository as a deploy key.
name
 yes
The name for the deploy key.
aliases: title, label
otp
 no
The 6 digit One Time Password for 2-Factor Authentication. Required together with username and password.
owner
 yes
The name of the individual account or organization that owns the GitHub repository.
aliases: account, organization
password
 no
The password to authenticate with. A personal access token can be used here in place of a password.
read_only
 no True
  • yes
  • no
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
 yes
The name of the GitHub repository.
aliases: repository
state
 no present
  • present
  • absent
The state of the deploy key.
token
 no
The OAuth2 token or personal access token to authenticate with. Mutually exclusive with password.
username
 no
The username to authenticate with.

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

name description returned type sample
error
the error message returned by the GitHub API
failed string key is already in use
http_status_code
the HTTP status code returned by the GitHub API
failed int 400
id
the key identifier assigned by GitHub for the deploy key
changed int 24381901
msg
the status message describing what occurred
always string Deploy key added successfully

Notes

Note

Status

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

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

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