community.general.gitlab_hook module – Manages GitLab project hooks

Note

This module is part of the community.general collection (version 9.4.0).

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. You need further requirements to be able to use this module, see Requirements for details.

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

Comments

api_job_token

string

added in community.general 4.2.0

GitLab CI job token for logging in.

api_oauth_token

string

added in community.general 4.2.0

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.

ca_path

string

added in community.general 8.1.0

The CA certificates bundle to use to verify GitLab server certificate.

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

aliases: enable_ssl_verification

boolean

Whether GitLab will do SSL verification when triggering the hook.

Choices:

  • false ← (default)

  • true

issues_events

boolean

Trigger hook on issues events.

Choices:

  • false ← (default)

  • true

job_events

boolean

Trigger hook on job events.

Choices:

  • false ← (default)

  • true

merge_requests_events

boolean

Trigger hook on merge requests events.

Choices:

  • false ← (default)

  • true

note_events

boolean

Trigger hook on note events or when someone adds a comment.

Choices:

  • false ← (default)

  • true

pipeline_events

boolean

Trigger hook on pipeline events.

Choices:

  • false ← (default)

  • true

project

string / required

Id or Full path of the project in the form of group/name.

push_events

boolean

Trigger hook on push events.

Choices:

  • false

  • true ← (default)

push_events_branch_filter

string

added in community.general 0.2.0

Branch name of wildcard to trigger hook on push events

Default: ""

releases_events

boolean

added in community.general 8.4.0

Trigger hook on release events.

Choices:

  • false

  • true

state

string

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.

Choices:

  • "present" ← (default)

  • "absent"

tag_push_events

boolean

Trigger hook on tag push events.

Choices:

  • false ← (default)

  • true

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

Whether or not to validate SSL certs when supplying a HTTPS endpoint.

Choices:

  • false

  • true ← (default)

wiki_page_events

boolean

Trigger hook on wiki events.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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: true
    tag_push_events: true
    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

Description

error

string

the error message returned by the GitLab API

Returned: failed

Sample: "400: path is already in use"

hook

dictionary

API object

Returned: always

msg

string

Success or failure message

Returned: always

Sample: "Success"

result

dictionary

json parsed response from the server

Returned: always

Authors

  • Marcus Watkins (@marwatk)

  • Guillaume Martinez (@Lunik)