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

Note

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

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.

Parameters

Parameter Choices/Defaults Comments
api_job_token
string
added in 4.2.0 of community.general
GitLab CI job token for logging in.
api_oauth_token
string
added in 4.2.0 of community.general
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
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.
avatar_path
path
added in 4.2.0 of community.general
Absolute path image to configure avatar. File size should not exceed 200 kb.
This option is only used on creation, not for updates.
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)