gitlab_hook – Manages GitLab project hooks — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# gitlab_hook – Manages GitLab project hooks

New in version 2.6.

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

## Synopsis

- Adds, updates and removes project hook

Aliases: gitlab_hooks

## 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
hook_url string / required |  | The url that you want GitLab to post to, this is used as the primary key for updates and deletion.
hook_validate_certs boolean | Choices: no ← yes | Whether GitLab will do SSL verification when triggering the hook. aliases: enable_ssl_verification
issues_events boolean | Choices: no ← yes | Trigger hook on issues events.
job_events boolean | Choices: no ← yes | Trigger hook on job events.
merge_requests_events boolean | Choices: no ← yes | Trigger hook on merge requests events.
note_events boolean | Choices: no ← yes | Trigger hook on note events or when someone adds a comment.
pipeline_events boolean | Choices: no ← yes | Trigger hook on pipeline events.
project string / required |  | Id or Full path of the project in the form of group/name.
push_events boolean | Choices: no yes ← | Trigger hook on push events.
state string / required | Choices: present ← absent | When `present` the hook will be updated to match the input or created if it doesn't exist. When `absent` hook will be deleted if it exists.
tag_push_events boolean | Choices: no ← yes | Trigger hook on tag push events.
token string |  | Secret token to validate hook messages at the receiver. If this is present it will always result in a change as it cannot be retrieved from GitLab. Will show up in the X-GitLab-Token HTTP request header.
validate_certs boolean | Choices: no yes ← | Whether or not to validate SSL certs when supplying a https endpoint.
wiki_page_events boolean | Choices: no ← yes | Trigger hook on wiki events.

## Examples

    - name: "Adding a project hook"
      gitlab_hook:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_token }}"
        project: "my_group/my_project"
        hook_url: "https://my-ci-server.example.com/gitlab-hook"
        state: present
        push_events: yes
        tag_push_events: yes
        hook_validate_certs: no
        token: "my-super-secret-token-that-my-ci-server-will-check"

    - name: "Delete the previous hook"
      gitlab_hook:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_token }}"
        project: "my_group/my_project"
        hook_url: "https://my-ci-server.example.com/gitlab-hook"
        state: absent

    - name: "Delete a hook by numeric project id"
      gitlab_hook:
        api_url: https://gitlab.example.com/
        api_token: "{{ access_token }}"
        project: 10
        hook_url: "https://my-ci-server.example.com/gitlab-hook"
        state: absent

## 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 GitLab API Sample: 400: path is already in use
hook dictionary | always | API object
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.