Gitlab Module Guidelines

General Coding Guidelines for Gitlab Modules

Note: This section is still under development

General Rules

• modules should support check_mode
• the module must use the python-gitlab API to make API calls.
• modules should include integration tests (test/integration/targets)

Input Parameters

• Usage of auth_basic doc_fragments
• Usage of auth_basic module utils from api which provides this options

name	required	default	Description	Example
api_url	yes		The resolvable endpoint for the API	"https://gitlab.com"
api_username			The username to use for authentication against the API
api_password			The password to use for authentication against the API
validate_certs		yes	Whether or not to validate SSL certs when supplying a https endpoint.

• Then Gitlab parameters:

name	required	default	Description	Example
api_token			Login token for Gitlab API authentication. (Private token generated on the Gitlab Interface)

Parameters conditions

parameters	condition
api_username & api_token	mutually_exclusive
api_password & api_token	mutually_exclusive
api_username & api_password	required_together
api_username & api_token	required_one_of

Return values for main modules

Return values should include only minimal information:

• resource object
• any specific information allocated by the service that is important for the user

Idempotence

• modules should be idempotent -- calling with the same options should not result in any change
• there may be some exceptions, for instance passwords, when they can't be compared with existing passwords. When password option is not specified, it should be omitted in idempotence check. Specifying password should cause update.

How to implement idempotence?

The most robust approach is as follows:

1. query current_resource_state structure/dictionary
2. construct new_resource_state from input parameters
3. compare new_resource_state with current_resource_state
4. update current_resource_state with new_resource_state
5. use updated current_resource_state to call create or create_or_update function

Please note that currently no module is entirely using this approach. Points (4) and (5) are important in order to preserve properties of resource that was not created by Ansible module and may have some properties that are not supported by current version of the module.

Testing

Tests that need to be performed on every module

• create resource
• create resource again with the same parameters, make sure no change was recorded
• create resource again with different parameters, make sure proper changes were made and change was recorded
• delete resource, make sure change was recorded
• delete non-existing resource, make sure no change was recorder

Testing Idempotence

• every field that should be idempotent shall be tested using check_mode
• single update test should be done with changes to all fields to check if they were updated correctly