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
    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. Alternatively, a personal access token can be used instead of username and password combination.
read_only
boolean
    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. Should not be set when using personal access token

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.