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 |
|
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 |
|
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 |
|
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
- Refer to GitHub’s API documentation here: https://developer.github.com/v3/repos/keys/.
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