W3cubDocs

/Ansible

community.general.gitlab_user – Creates/updates/deletes/blocks/unblocks GitLab Users

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

Synopsis

  • When the user does not exist in GitLab, it will be created.
  • When the user exists and state=absent, the user will be deleted.
  • When the user exists and state=blocked, the user will be blocked.
  • When changes are made to user, the user will be updated.

Requirements

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

  • python >= 2.7
  • python-gitlab python module
  • administrator rights on the GitLab server

Parameters

Parameter Choices/Defaults Comments
access_level
string
    Choices:
  • guest ←
  • reporter
  • developer
  • master
  • maintainer
  • owner
The access level to the group. One of the following can be used.
guest
reporter
developer
master (alias for maintainer)
maintainer
owner
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
confirm
boolean
    Choices:
  • no
  • yes ←
Require confirmation.
email
string
The email that belongs to the user.
Required only if state is set to present.
external
boolean
    Choices:
  • no ←
  • yes
Define external parameter for this user.
group
string
Id or Full path of parent group in the form of group/name.
Add user as a member to this group.
identities
list / elements=dictionary
added in 3.3.0 of community.general
List of identities to be added/updated for this user.
To remove all other identities from this user, set overwrite_identities=true.
extern_uid
string
User ID for external identity.
provider
string
The name of the external identity provider
isadmin
boolean
    Choices:
  • no ←
  • yes
Grant admin privileges to the user.
name
string
Name of the user you want to create.
Required only if state is set to present.
overwrite_identities
boolean
added in 3.3.0 of community.general
    Choices:
  • no ←
  • yes
Overwrite identities with identities added in this module.
This means that all identities that the user has and that are not listed in identities are removed from the user.
This is only done if a list is provided for identities. To remove all identities, provide an empty list.
password
string
The password of the user.
GitLab server enforces minimum password length to 8, set this value with 8 or more characters.
Required only if state is set to present.
reset_password
boolean
added in 3.3.0 of community.general
    Choices:
  • no ←
  • yes
Whether the user can change its password or not.
sshkey_expires_at
string
added in 3.1.0 of community.general
The expiration date of the SSH public key in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
This is only used when adding new SSH public keys.
sshkey_file
string
The SSH public key itself.
sshkey_name
string
The name of the SSH public key.
state
string
    Choices:
  • present ←
  • absent
  • blocked
  • unblocked
Create, delete or block a user.
username
string / required
The username of the user.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether or not to validate SSL certs when supplying a https endpoint.

Notes

Note

  • From community.general 0.2.0 and onwards, name, email and password are optional while deleting the user.

Examples

- name: "Delete GitLab User"
  community.general.gitlab_user:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    validate_certs: False
    username: myusername
    state: absent

- name: "Create GitLab User"
  community.general.gitlab_user:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_username: dj-wasabi
    api_password: "MySecretPassword"
    name: My Name
    username: myusername
    password: mysecretpassword
    email: [email protected]
    sshkey_name: MySSH
    sshkey_file: ssh-rsa AAAAB3NzaC1yc...
    state: present
    group: super_group/mon_group
    access_level: owner

- name: "Create GitLab User using external identity provider"
  community.general.gitlab_user:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_token: "{{ access_token }}"
    name: My Name
    username: myusername
    password: mysecretpassword
    email: [email protected]
    identities:
    - provider: Keycloak
      extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc
    state: present
    group: super_group/mon_group
    access_level: owner

- name: "Block GitLab User"
  community.general.gitlab_user:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    validate_certs: False
    username: myusername
    state: blocked

- name: "Unblock GitLab User"
  community.general.gitlab_user:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    validate_certs: False
    username: myusername
    state: unblocked

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
msg
string
always
Success or failure message

Sample:
Success
result
dictionary
always
json parsed response from the server
user
dictionary
always
API object


Authors

  • Werner Dijkerman (@dj-wasabi)
  • Guillaume Martinez (@Lunik)
  • Lennert Mertens (@LennertMertens)
  • Stef Graces (@stgrace)

© 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_user_module.html