Skip to content
This repository has been archived by the owner on Jun 10, 2024. It is now read-only.

Gitlab Module Guidelines

Guillaume Martinez edited this page Feb 7, 2019 · 4 revisions

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

(ARchived) Working groups

Working groups are now in the Ansible forum

Ansible project:
Community, Contributor Experience, Docs, News, Outreach, RelEng, Testing

Cloud:
AWS, Azure, CloudStack, Container, DigitalOcean, Docker, hcloud, Kubernetes, Linode, OpenStack, oVirt, Virt, VMware

Networking:
ACI, AVI, F5, Meraki, Network, NXOS

Ansible Developer Tools:
Ansible-developer-tools

Software:
Crypto, Foreman, GDrive, GitLab, Grafana, IPA, JBoss, MongoDB, MySQL, PostgreSQL, RabbitMQ, Zabbix

System:
AIX, BSD, HP-UX, macOS, Remote Management, Solaris, Windows

Security:
Security-Automation, Lockdown

Tooling:
AWX, Galaxy, Molecule

Communities

Modules:
unarchive, xml

Plugins:
httpapi

Wiki

Roles, Communication, Reviewing, Checklist, TODO

Clone this wiki locally