community.general.github_deploy_key – Manages deploy keys for GitHub repositories.
Note
This plugin is part of the community.general collection (version 3.8.3).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
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 |
Comments |
---|---|
If Choices:
|
|
The base URL of the GitHub API Default: “https://api.github.com” |
|
The SSH public key to add to the repository as a deploy key. |
|
The name for the deploy key. |
|
The 6 digit One Time Password for 2-Factor Authentication. Required together with username and password. Alias |
|
The name of the individual account or organization that owns the GitHub repository. |
|
The password to authenticate with. Alternatively, a personal access token can be used instead of username and password combination. |
|
If Choices:
|
|
The name of the GitHub repository. |
|
The state of the deploy key. Choices:
|
|
The OAuth2 token or personal access token to authenticate with. Mutually exclusive with password. |
|
The username to authenticate with. Should not be set when using personal access token |
Notes
Note
Refer to GitHub’s API documentation here: https://developer.github.com/v3/repos/keys/.
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 |
Description |
---|---|
the error message returned by the GitHub API Returned: failed Sample: “key is already in use” |
|
the HTTP status code returned by the GitHub API Returned: failed Sample: 400 |
|
the key identifier assigned by GitHub for the deploy key Returned: changed Sample: 24381901 |
|
the status message describing what occurred Returned: always Sample: “Deploy key added successfully” |
Authors
Ali (@bincyber)