community.general.github_deploy_key (8.5.0) — module

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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: true
    username: "johndoe"
    password: "supersecretpassword"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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: true
    username: "johndoe"
    password: "supersecretpassword"
    state: absent

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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: true
    token: "ABAQDAwXxn7kIMNWzcDfo..."

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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: true
    username: "janedoe"
    password: "supersecretpassword"

Inputs

    
key:
    description:
    - The SSH public key to add to the repository as a deploy key.
    required: true
    type: str

otp:
    description:
    - The 6 digit One Time Password for 2-Factor Authentication. Required together with
      O(username) and O(password).
    type: int

name:
    aliases:
    - title
    - label
    description:
    - The name for the deploy key.
    required: true
    type: str

repo:
    aliases:
    - repository
    description:
    - The name of the GitHub repository.
    required: true
    type: str

force:
    default: false
    description:
    - If V(true), forcefully adds the deploy key by deleting any existing deploy key with
      the same public key or title.
    type: bool

owner:
    aliases:
    - account
    - organization
    description:
    - The name of the individual account or organization that owns the GitHub repository.
    required: true
    type: str

state:
    choices:
    - present
    - absent
    default: present
    description:
    - The state of the deploy key.
    type: str

token:
    description:
    - The OAuth2 token or personal access token to authenticate with. Mutually exclusive
      with O(password).
    type: str

password:
    description:
    - The password to authenticate with. Alternatively, a personal access token can be
      used instead of O(username) and O(password) combination.
    type: str

username:
    description:
    - The username to authenticate with. Should not be set when using personal access
      token
    type: str

read_only:
    default: true
    description:
    - If V(true), the deploy key will only be able to read repository contents. Otherwise,
      the deploy key will be able to read and write.
    type: bool

github_url:
    default: https://api.github.com
    description:
    - The base URL of the GitHub API
    required: false
    type: str
    version_added: 0.2.0
    version_added_collection: community.general

Outputs

error:
  description: the error message returned by the GitHub API
  returned: failed
  sample: key is already in use
  type: str
http_status_code:
  description: the HTTP status code returned by the GitHub API
  returned: failed
  sample: 400
  type: int
id:
  description: the key identifier assigned by GitHub for the deploy key
  returned: changed
  sample: 24381901
  type: int
msg:
  description: the status message describing what occurred
  returned: always
  sample: Deploy key added successfully
  type: str