gitlab_hooks - Manages GitLab project hooks.

New in version 2.6.

Synopsis

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
bool
    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
bool
    Choices:
  • no ←
  • yes
Trigger hook on issues events
job_events
bool
    Choices:
  • no ←
  • yes
Trigger hook on job events
merge_requests_events
bool
    Choices:
  • no ←
  • yes
Trigger hook on merge requests events
note_events
bool
    Choices:
  • no ←
  • yes
Trigger hook on note events
pipeline_events
bool
    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
bool
    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
bool
    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
bool
    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
dict
 changed
object describing the state prior to this task
result
dict
 always
json parsed response from the server


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Marcus Watkins (@marwatk)

Hint

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