# gitlab_deploy_key – Manages GitLab project deploy keys

New in version 2.6.

- Synopsis
- Requirements
- Parameters
- Examples
- Return Values
- Status

## 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 <= 1.12.1

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_password string |  | The password to use for authentication against the API
api_token string added in 2.8 |  | GitLab token for logging in. aliases: private_token, access_token
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 / required

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"
      gitlab_deploy_key:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_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"
      gitlab_deploy_key:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_token }}"
        project: "my_group/my_project"
        title: "Jenkins CI"
        state: present
        can_push: yes

    - name: "Remove the previous deploy key from the project"
      gitlab_deploy_key:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

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

Hint

If you notice any issues in this documentation, you can edit this document to improve it.