community.general.gitlab_hook – Manages GitLab project hooks.

Note

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

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.gitlab_hook.

Synopsis
Requirements
Parameters
Examples
Return Values

Synopsis

Adds, updates and removes project hook

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
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	no ← yes	Whether GitLab will do SSL verification when triggering the hook. aliases: enable_ssl_verification
issues_events boolean	no ← yes	Trigger hook on issues events.
job_events boolean	no ← yes	Trigger hook on job events.
merge_requests_events boolean	no ← yes	Trigger hook on merge requests events.
note_events boolean	no ← yes	Trigger hook on note events or when someone adds a comment.
pipeline_events boolean	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	no yes ←	Trigger hook on push events.
push_events_branch_filter string added in 0.2.0 of community.general		Branch name of wildcard to trigger hook on push events
state string	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	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	no yes ←	Whether or not to validate SSL certs when supplying a https endpoint.
wiki_page_events boolean	no ← yes	Trigger hook on wiki events.

Examples

- name: "Adding a project hook"
  community.general.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"
  community.general.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"
  community.general.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

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/2.11/collections/community/general/gitlab_hook_module.html