gitlab_hook – Manages GitLab project hooks

New in version 2.6.

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

Authors

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

Hint

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