gitlab_hooks – Manages GitLab project hooks.

New in version 2.6.

Synopsis

  • Adds, updates and removes project hooks

Parameters

Parameter Choices/Defaults Comments
access_token
-
The oauth key provided by GitLab. One of access_token or private_token is required. See https://docs.gitlab.com/ee/api/oauth2.html
api_url
- / required
GitLab API url, e.g. https://gitlab.example.com/api
enable_ssl_verification
boolean
    Choices:
  • no ←
  • yes
Whether GitLab will do SSL verification when triggering the hook
hook_url
- / required
The url that you want GitLab to post to, this is used as the primary key for updates and deletion.
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
pipeline_events
boolean
    Choices:
  • no ←
  • yes
Trigger hook on pipeline events
private_token
-
Personal access token to use. One of private_token or access_token is required. See https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html
project
- / required
Numeric project id or name of project in the form of group/name
push_events
boolean
    Choices:
  • no
  • yes ←
Trigger hook on push events
state
- / required
    Choices:
  • present ←
  • absent
When present the hook will be updated to match the input or created if it doesn't exist. When absent it will be deleted if it exists.
tag_push_events
boolean
    Choices:
  • no ←
  • yes
Trigger hook on tag push events
token
-
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
wiki_page_events
boolean
    Choices:
  • no ←
  • yes
Trigger hook on wiki events

Examples

# Example creating a new project hook
- gitlab_hooks:
    api_url: https://gitlab.example.com/api
    access_token: "{{ access_token }}"
    project: "my_group/my_project"
    hook_url: "https://my-ci-server.example.com/gitlab-hook"
    state: present
    push_events: yes
    enable_ssl_verification: no
    token: "my-super-secret-token-that-my-ci-server-will-check"

# Update the above hook to add tag pushes
- gitlab_hooks:
    api_url: https://gitlab.example.com/api
    access_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
    enable_ssl_verification: no
    token: "my-super-secret-token-that-my-ci-server-will-check"

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

# Delete a hook by numeric project id
- gitlab_hooks:
    api_url: https://gitlab.example.com/api
    access_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: key is already in use
msg
string
 always
Success or failure message

Sample:
Success
previous_version
dictionary
 changed
object describing the state prior to this task
result
dictionary
 always
json parsed response from the server


Status

Authors

  • Marcus Watkins (@marwatk)

Hint

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