github_deploy_key – Manages deploy keys for GitHub repositories.

From Get docs
Ansible/docs/2.7/modules/github deploy key module


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

boolean

  • no

  • yes

If true, forcefully adds the deploy key by deleting any existing deploy key with the same public key or title.

key

- / required

The SSH public key to add to the repository as a deploy key.

name

- / required

The name for the deploy key.


aliases: title, label

otp

-

The 6 digit One Time Password for 2-Factor Authentication. Required together with username and password.


aliases: 2fa_token

owner

- / required

The name of the individual account or organization that owns the GitHub repository.


aliases: account, organization

password

-

The password to authenticate with. A personal access token can be used here in place of a password.

read_only

boolean

  • 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

The name of the GitHub repository.


aliases: repository

state

-

  • present

  • absent

The state of the deploy key.

token

-

The OAuth2 token or personal access token to authenticate with. Mutually exclusive with password.

username

-

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

integer

failed

the HTTP status code returned by the GitHub API


Sample:

400

id

integer

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

Authors

  • 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.7/modules/github_deploy_key_module.html