community.general.gitlab_group – Creates/updates/deletes GitLab Groups

Note

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

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

Synopsis

When the group does not exist in GitLab, it will be created.
When the group does exist and state=absent, the group will be deleted.

Requirements

The below requirements are needed on the host that executes this module.

python >= 2.7
python-gitlab python module

Parameters

Parameter	Choices/Defaults	Comments
api_password string		The password to use for authentication against the API
api_token string		GitLab token for logging in.
api_url string		The resolvable endpoint for the API
api_username string		The username to use for authentication against the API
auto_devops_enabled boolean added in 3.7.0 of community.general	Choices: no yes	Default to Auto DevOps pipeline for all projects within this group.
description string		A description for the group.
name string / required		Name of the group you want to create.
parent string		Allow to create subgroups Id or Full path of parent group in the form of group/name
path string		The path of the group you want to create, this will be api_url/group_path If not supplied, the group_name will be used.
project_creation_level string added in 3.7.0 of community.general	Choices: developer maintainer noone	Determine if developers can create projects in the group.
require_two_factor_authentication boolean added in 3.7.0 of community.general	Choices: no yes	Require all users in this group to setup two-factor authentication.
state string	Choices: present ← absent	create or delete group. Possible values are present and absent.
subgroup_creation_level string added in 3.7.0 of community.general	Choices: maintainer owner	Allowed to create subgroups.
validate_certs boolean	Choices: no yes ←	Whether or not to validate SSL certs when supplying a https endpoint.
visibility string	Choices: private ← internal public	Default visibility of the group

Examples

- name: "Delete GitLab Group"
  community.general.gitlab_group:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    validate_certs: False
    name: my_first_group
    state: absent

- name: "Create GitLab Group"
  community.general.gitlab_group:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_username: dj-wasabi
    api_password: "MySecretPassword"
    name: my_first_group
    path: my_first_group
    state: present

# The group will by created at https://gitlab.dj-wasabi.local/super_parent/parent/my_first_group
- name: "Create GitLab SubGroup"
  community.general.gitlab_group:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_username: dj-wasabi
    api_password: "MySecretPassword"
    name: my_first_group
    path: my_first_group
    state: present
    parent: "super_parent/parent"

# Other group which only allows sub-groups - no projects
- name: "Create GitLab Group for SubGroups only"
  community.general.gitlab_group:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_username: dj-wasabi
    api_password: "MySecretPassword"
    name: my_main_group
    path: my_main_group
    state: present
    project_creation_level: noone
    auto_devops_enabled: false
    subgroup_creation_level: maintainer

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
group dictionary	always	API object
msg string	always	Success or failure message Sample: Success
result dictionary	always	json parsed response from the server

Authors

Werner Dijkerman (@dj-wasabi)
Guillaume Martinez (@Lunik)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/gitlab_group_module.html

Docs

Docs4dev

Title here