community.general.gitlab_hook – Manages GitLab project hooks.

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

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

Docs

Docs4dev

Title here