github_deploy_key - Manages deploy keys for GitHub repositories.

New in version 2.4.

Synopsis

Requirements

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

  • python-requests

Parameters

Parameter Choices/Defaults Comments
force
bool
    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
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
bool
    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
The name of the GitHub repository.

aliases: repository
state
    Choices:
  • 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
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.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Ali (@bincyber)

Hint

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