Gitlab Module Guidelines - ansible/community GitHub Wiki
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 fromapi
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:
- query current_resource_state structure/dictionary
- construct new_resource_state from input parameters
- compare new_resource_state with current_resource_state
- update current_resource_state with new_resource_state
- 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