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

Note

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

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

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

Default to Auto DevOps pipeline for all projects within this group.

Choices:

  • no

  • yes

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

Determine if developers can create projects in the group.

Choices:

  • developer

  • maintainer

  • noone

require_two_factor_authentication

boolean

added in 3.7.0 of community.general

Require all users in this group to setup two-factor authentication.

Choices:

  • no

  • yes

state

string

create or delete group.

Possible values are present and absent.

Choices:

  • present ← (default)

  • absent

subgroup_creation_level

string

added in 3.7.0 of community.general

Allowed to create subgroups.

Choices:

  • maintainer

  • owner

validate_certs

boolean

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

Choices:

  • no

  • yes ← (default)

visibility

string

Default visibility of the group

Choices:

  • private ← (default)

  • internal

  • public

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

Description

error

string

the error message returned by the GitLab API

Returned: failed

Sample: “400: path is already in use”

group

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

  • Werner Dijkerman (@dj-wasabi)

  • Guillaume Martinez (@Lunik)