community.general.github_deploy_key – Manages deploy keys for GitHub repositories.

Note

This plugin is part of the community.general collection (version 2.5.1).

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.github_deploy_key.

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. Admin rights on the repository are required.

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.
github_url
string
added in 0.2.0 of community.general
Default:
"https://api.github.com"
The base URL of the GitHub API
key
string / required
The SSH public key to add to the repository as a deploy key.
name
string / required
The name for the deploy key.

aliases: title, label
otp
integer
The 6 digit One Time Password for 2-Factor Authentication. Required together with username and password.
Alias 2fa_token has been deprecated and will be removed in community.general 5.0.0.

aliases: 2fa_token
owner
string / required
The name of the individual account or organization that owns the GitHub repository.

aliases: account, organization
password
string
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
string / required
The name of the GitHub repository.

aliases: repository
state
string
    Choices:
  • present ←
  • absent
The state of the deploy key.
token
string
The OAuth2 token or personal access token to authenticate with. Mutually exclusive with password.
username
string
The username to authenticate with. Should not be set when using personal access token

Notes

Note

Examples

- name: Add a new read-only deploy key to a GitHub repository using basic authentication
  community.general.github_deploy_key:
    owner: "johndoe"
    repo: "example"
    name: "new-deploy-key"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    read_only: yes
    username: "johndoe"
    password: "supersecretpassword"

- name: Remove an existing deploy key from a GitHub repository
  community.general.github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "new-deploy-key"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    force: yes
    username: "johndoe"
    password: "supersecretpassword"
    state: absent

- name: Add a new deploy key to a GitHub repository, replace an existing key, use an OAuth2 token to authenticate
  community.general.github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "new-deploy-key"
    key: "{{ lookup('file', '~/.ssh/github.pub') }}"
    force: yes
    token: "ABAQDAwXxn7kIMNWzcDfo..."

- name: Re-add a deploy key to a GitHub repository but with a different name
  community.general.github_deploy_key:
    owner: "johndoe"
    repository: "example"
    name: "replace-deploy-key"
    key: "{{ lookup('file', '~/.ssh/github.pub') }}"
    username: "johndoe"
    password: "supersecretpassword"

- name: Add a new deploy key to a GitHub repository using 2FA
  community.general.github_deploy_key:
    owner: "johndoe"
    repo: "example"
    name: "new-deploy-key-2"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    username: "johndoe"
    password: "supersecretpassword"
    otp: 123456

- name: Add a read-only deploy key to a repository hosted on GitHub Enterprise
  community.general.github_deploy_key:
    github_url: "https://api.example.com"
    owner: "janedoe"
    repo: "example"
    name: "new-deploy-key"
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDAwXxn7kIMNWzcDfou..."
    read_only: yes
    username: "janedoe"
    password: "supersecretpassword"

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


Authors

  • Ali (@bincyber)