community.general.gitlab_hook – Manages GitLab project hooks.

Note

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

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.

Parameters

Parameter Choices/Defaults Comments
api_job_token
string
added in 4.2.0 of community.general
GitLab CI job token for logging in.
api_oauth_token
string
added in 4.2.0 of community.general
GitLab OAuth token for logging in.
api_password
string
The password to use for authentication against the API
api_token
string
GitLab access token with API permissions.
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)