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

Note

This module is part of the community.general collection (version 10.1.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. 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_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

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.

auto_devops_enabled

boolean

added in community.general 3.7.0

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

Choices:

  • false

  • true

avatar_path

path

added in community.general 4.2.0

Absolute path image to configure avatar. File size should not exceed 200 kb.

This option is only used on creation, not for updates.

ca_path

string

added in community.general 8.1.0

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

default_branch

string

added in community.general 9.5.0

All merge requests and commits are made against this branch unless you specify a different one.

description

string

A description for the group.

enabled_git_access_protocol

string

added in community.general 9.5.0

all means SSH and HTTP(S) is enabled.

ssh means only SSH is enabled.

http means only HTTP(S) is enabled.

Only available for top level groups.

Choices:

  • "all"

  • "ssh"

  • "http"

force_delete

boolean

added in community.general 7.5.0

Force delete group even if projects in it.

Used only when state=absent.

Choices:

  • false ← (default)

  • true

lfs_enabled

boolean

added in community.general 9.5.0

Projects in this group can use Git LFS.

Choices:

  • false

  • true

lock_duo_features_enabled

boolean

added in community.general 9.5.0

Enforce GitLab Duo features for all subgroups.

Only available for top level groups.

Choices:

  • false

  • true

membership_lock

boolean

added in community.general 9.5.0

Users cannot be added to projects in this group.

Choices:

  • false

  • true

mentions_disabled

boolean

added in community.general 9.5.0

Group mentions are disabled.

Choices:

  • false

  • true

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.

prevent_forking_outside_group

boolean

added in community.general 9.5.0

Prevent forking outside of the group.

Choices:

  • false

  • true

prevent_sharing_groups_outside_hierarchy

boolean

added in community.general 9.5.0

Members cannot invite groups outside of this group and its subgroups.

Only available for top level groups.

Choices:

  • false

  • true

project_creation_level

string

added in community.general 3.7.0

Determine if developers can create projects in the group.

Choices:

  • "developer"

  • "maintainer"

  • "noone"

request_access_enabled

boolean

added in community.general 9.5.0

Users can request access (if visibility is public or internal).

Choices:

  • false

  • true

require_two_factor_authentication

boolean

added in community.general 3.7.0

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

Choices:

  • false

  • true

service_access_tokens_expiration_enforced

boolean

added in community.general 9.5.0

Service account token expiration.

Changes will not affect existing token expiration dates.

Only available for top level groups.

Choices:

  • false

  • true

share_with_group_lock

boolean

added in community.general 9.5.0

Projects cannot be shared with other groups.

Choices:

  • false

  • true

state

string

create or delete group.

Possible values are present and absent.

Choices:

  • "present" ← (default)

  • "absent"

subgroup_creation_level

string

added in community.general 3.7.0

Allowed to create subgroups.

Choices:

  • "maintainer"

  • "owner"

two_factor_grace_period

string

added in community.general 9.5.0

Delay 2FA enforcement (hours).

validate_certs

boolean

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

Choices:

  • false

  • true ← (default)

visibility

string

Default visibility of the group

Choices:

  • "private" ← (default)

  • "internal"

  • "public"

wiki_access_level

string

added in community.general 9.5.0

enabled means everyone can access the wiki.

private means only members of this group can access the wiki.

disabled means group-level wiki is disabled.

Choices:

  • "enabled"

  • "private"

  • "disabled"

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: "Delete GitLab Group"
  community.general.gitlab_group:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    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)