community.general.gitlab_deploy_key – Manages GitLab project deploy keys.

Note

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

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.gitlab_deploy_key.

Synopsis

  • Adds, updates and removes project deploy keys

Requirements

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

  • python >= 2.7
  • python-gitlab python module

Parameters

Parameter Choices/Defaults Comments
api_password
string
The password to use for authentication against the API
api_token
string
GitLab token for logging in.
api_url
string
The resolvable endpoint for the API
api_username
string
The username to use for authentication against the API
can_push
boolean
    Choices:
  • no ←
  • yes
Whether this key can push to the project.
key
string / required
Deploy key
project
string / required
Id or Full path of project in the form of group/name.
state
string
    Choices:
  • present ←
  • absent
When present the deploy key added to the project if it doesn't exist.
When absent it will be removed from the project if it exists.
title
string / required
Deploy key's title.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether or not to validate SSL certs when supplying a https endpoint.

Examples

- name: "Adding a project deploy key"
  community.general.gitlab_deploy_key:
    api_url: https://gitlab.example.com/
    api_token: "{{ api_token }}"
    project: "my_group/my_project"
    title: "Jenkins CI"
    state: present
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9w..."

- name: "Update the above deploy key to add push access"
  community.general.gitlab_deploy_key:
    api_url: https://gitlab.example.com/
    api_token: "{{ api_token }}"
    project: "my_group/my_project"
    title: "Jenkins CI"
    state: present
    can_push: yes

- name: "Remove the previous deploy key from the project"
  community.general.gitlab_deploy_key:
    api_url: https://gitlab.example.com/
    api_token: "{{ api_token }}"
    project: "my_group/my_project"
    state: absent
    key: "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9w..."

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
deploy_key
dictionary
always
API object
error
string
failed
the error message returned by the GitLab API

Sample:
400: key is already in use
msg
string
always
Success or failure message

Sample:
Success
result
dictionary
always
json parsed response from the server


Authors

  • Marcus Watkins (@marwatk)
  • Guillaume Martinez (@Lunik)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/gitlab_deploy_key_module.html