gitlab_hook – Manages GitLab project hooks

From Get docs
Ansible/docs/2.8/modules/gitlab hook module


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

  • no

  • yes

Whether GitLab will do SSL verification when triggering the hook


aliases: enable_ssl_verification

issues_events

boolean

  • no

  • yes

Trigger hook on issues events

job_events

boolean

  • no

  • yes

Trigger hook on job events

merge_requests_events

boolean

  • no

  • yes

Trigger hook on merge requests events

note_events

boolean

  • no

  • yes

Trigger hook on note events

pipeline_events

boolean

  • 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

  • no
  • yes

Trigger hook on push events

state

string / required

  • 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

  • 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

  • no
  • yes

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

wiki_page_events

boolean

  • 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.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/gitlab_hook_module.html