community.general.gitlab_hook – Manages GitLab project hooks.

Note

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

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)