a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

g*.py: normalize docs (#9395) 

* g*.py: normalize docs

* Update plugins/modules/gandi_livedns.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9420/head
Alexei Znamensky 2024-12-27 09:54:03 +13:00 committed by GitHub
parent df42f29e53
commit 3048d5305d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
36 changed files with 633 additions and 683 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
plugins/modules/gandi_livedns.py
View File

@ -8,15 +8,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: gandi_livedns
author:
- Gregory Thiemonge (@gthiemonge)
version_added: "2.3.0"
short_description: Manage Gandi LiveDNS records
description:
- "Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/)."
- 'Manages DNS records by the Gandi LiveDNS API, see the docs: U(https://doc.livedns.gandi.net/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,32 +26,31 @@ attributes:
options:
personal_access_token:
description:
- Scoped API token.
- One of O(personal_access_token) and O(api_key) must be specified.
- Scoped API token.
- One of O(personal_access_token) and O(api_key) must be specified.
type: str
version_added: 9.0.0
api_key:
description:
- Account API token.
- Note that these type of keys are deprecated and might stop working at some point.
Use personal access tokens instead.
- One of O(personal_access_token) and O(api_key) must be specified.
- Account API token.
- Note that these type of keys are deprecated and might stop working at some point. Use personal access tokens instead.
- One of O(personal_access_token) and O(api_key) must be specified.
type: str
record:
description:
- Record to add.
- Record to add.
type: str
required: true
state:
description:
- Whether the record(s) should exist or not.
- Whether the record(s) should exist or not.
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
ttl:
description:
- The TTL to give the new record.
- Required when O(state=present).
- The TTL to give the new record.
- Required when O(state=present).
type: int
type:
description:
@ -61,25 +59,25 @@ options:
required: true
values:
description:
- The record values.
- Required when O(state=present).
- The record values.
- Required when O(state=present).
type: list
elements: str
domain:
description:
- The name of the Domain to work with (for example, "example.com").
- The name of the Domain to work with (for example, V(example.com)).
required: true
type: str
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Create a test A record to point to 127.0.0.1 in the my.com domain
community.general.gandi_livedns:
domain: my.com
record: test
type: A
values:
- 127.0.0.1
- 127.0.0.1
ttl: 7200
personal_access_token: dummytoken
register: record
@ -90,7 +88,7 @@ EXAMPLES = r'''
type: CNAME
record: mail
values:
- www
- www
ttl: 7200
personal_access_token: dummytoken
state: present
@ -101,7 +99,7 @@ EXAMPLES = r'''
type: CNAME
record: mail
values:
- www
- www
ttl: 10800
personal_access_token: dummytoken
state: present
@ -120,46 +118,46 @@ EXAMPLES = r'''
record: test
type: A
values:
- 127.0.0.1
- 127.0.0.1
ttl: 7200
api_key: dummyapikey
'''
"""
RETURN = r'''
RETURN = r"""
record:
description: A dictionary containing the record data.
returned: success, except on record deletion
type: dict
contains:
values:
description: The record content (details depend on record type).
returned: success
type: list
elements: str
sample:
- 192.0.2.91
- 192.0.2.92
record:
description: The record name.
returned: success
type: str
sample: www
ttl:
description: The time-to-live for the record.
returned: success
type: int
sample: 300
type:
description: The record type.
returned: success
type: str
sample: A
domain:
description: The domain associated with the record.
returned: success
type: str
sample: my.com
'''
description: A dictionary containing the record data.
returned: success, except on record deletion
type: dict
contains:
values:
description: The record content (details depend on record type).
returned: success
type: list
elements: str
sample:
- 192.0.2.91
- 192.0.2.92
record:
description: The record name.
returned: success
type: str
sample: www
ttl:
description: The time-to-live for the record.
returned: success
type: int
sample: 300
type:
description: The record type.
returned: success
type: str
sample: A
domain:
description: The domain associated with the record.
returned: success
type: str
sample: my.com
"""
from ansible.module_utils.basic import AnsibleModule

44
plugins/modules/gconftool2.py
View File

@ -9,21 +9,21 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: gconftool2
author:
- Kenneth D. Evensen (@kevensen)
- Kenneth D. Evensen (@kevensen)
short_description: Edit GNOME Configurations
description:
- This module allows for the manipulation of GNOME 2 Configuration via gconftool-2. Please see the gconftool-2(1) man pages for more details.
- This module allows for the manipulation of GNOME 2 Configuration using C(gconftool-2). Please see the gconftool-2(1) man pages
for more details.
seealso:
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -33,36 +33,37 @@ options:
key:
type: str
description:
- A GConf preference key is an element in the GConf repository that corresponds to an application preference.
- A GConf preference key is an element in the GConf repository that corresponds to an application preference.
required: true
value:
type: str
description:
- Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is ignored unless O(state=present).
- Preference keys typically have simple values such as strings, integers, or lists of strings and integers. This is
ignored unless O(state=present).
value_type:
type: str
description:
- The type of value being set. This is ignored unless O(state=present).
- The type of value being set. This is ignored unless O(state=present).
choices: [bool, float, int, string]
state:
type: str
description:
- The action to take upon the key/value.
- The action to take upon the key/value.
required: true
choices: [absent, present]
config_source:
type: str
description:
- Specify a configuration source to use rather than the default path.
- Specify a configuration source to use rather than the default path.
direct:
description:
- Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be specified as well.
- Access the config database directly, bypassing server. If O(direct) is specified then the O(config_source) must be
specified as well.
type: bool
default: false
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Change the widget font to "Serif 12"
community.general.gconftool2:
key: "/desktop/gnome/interface/font_name"
@ -70,8 +71,7 @@ EXAMPLES = """
value: "Serif 12"
"""
RETURN = """
---
RETURN = r"""
key:
description: The key specified in the module parameters.
returned: success
@ -84,15 +84,15 @@ value_type:
sample: string
value:
description:
- The value of the preference key after executing the module or V(null) if key is removed.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
- The value of the preference key after executing the module or V(null) if key is removed.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"
previous_value:
description:
- The value of the preference key before executing the module.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
- The value of the preference key before executing the module.
- From community.general 7.0.0 onwards it returns V(null) for a non-existent O(key), and returned V("") before that.
returned: success
type: str
sample: "Serif 12"

33
plugins/modules/gconftool2_info.py
View File

@ -7,46 +7,43 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: gconftool2_info
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Retrieve GConf configurations
version_added: 5.1.0
description:
- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
- This module allows retrieving application preferences from the GConf database, with the help of C(gconftool-2).
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
- community.general.attributes
- community.general.attributes.info_module
options:
key:
description:
- The key name for an element in the GConf database.
- The key name for an element in the GConf database.
type: str
required: true
seealso:
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
- name: gconf repository (archived)
description: Git repository for the project. It is an archived project, so the repository is read-only.
link: https://gitlab.gnome.org/Archive/gconf
- name: C(gconftool-2) command manual page
description: Manual page for the command.
link: https://help.gnome.org/admin//system-admin-guide/2.32/gconf-6.html.en
- name: gconf repository (archived)
description: Git repository for the project. It is an archived project, so the repository is read-only.
link: https://gitlab.gnome.org/Archive/gconf
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Get value for a certain key in the database.
community.general.gconftool2_info:
key: /desktop/gnome/background/picture_filename
register: result
"""
RETURN = """
---
RETURN = r"""
value:
description:
- The value of the property.
- The value of the property.
returned: success
type: str
sample: Monospace 10

32
plugins/modules/gem.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gem
short_description: Manage Ruby gems
description:
@ -49,38 +48,37 @@ options:
repository:
type: str
description:
- The repository from which the gem will be installed
- The repository from which the gem will be installed.
required: false
aliases: [source]
user_install:
description:
- Install gem in user's local gems cache or for all users
- Install gem in user's local gems cache or for all users.
required: false
type: bool
default: true
executable:
type: path
description:
- Override the path to the gem executable
- Override the path to the gem executable.
required: false
install_dir:
type: path
description:
- Install the gems into a specific directory.
These gems will be independent from the global installed ones.
Specifying this requires user_install to be false.
- Install the gems into a specific directory. These gems will be independent from the global installed ones. Specifying
this requires user_install to be false.
required: false
bindir:
type: path
description:
- Install executables into a specific directory.
- Install executables into a specific directory.
version_added: 3.3.0
norc:
type: bool
default: true
description:
- Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2.
- The default changed from V(false) to V(true) in community.general 6.0.0.
- Avoid loading any C(.gemrc) file. Ignored for RubyGems prior to 2.5.2.
- The default changed from V(false) to V(true) in community.general 6.0.0.
version_added: 3.3.0
env_shebang:
description:
@ -108,7 +106,7 @@ options:
build_flags:
type: str
description:
- Allow adding build flags for gem compilation
- Allow adding build flags for gem compilation.
required: false
force:
description:
@ -117,11 +115,11 @@ options:
default: false
type: bool
author:
- "Ansible Core Team"
- "Johan Wiren (@johanwiren)"
'''
- "Ansible Core Team"
- "Johan Wiren (@johanwiren)"
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install version 1.0 of vagrant
community.general.gem:
name: vagrant
@ -138,7 +136,7 @@ EXAMPLES = '''
name: rake
gem_source: /path/to/gems/rake-1.0.gem
state: present
'''
"""
import re

42
plugins/modules/gio_mime.py
View File

@ -7,17 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: gio_mime
author:
- "Alexei Znamensky (@russoz)"
- "Alexei Znamensky (@russoz)"
short_description: Set default handler for MIME type, for applications using Gnome GIO
version_added: 7.5.0
description:
- This module allows configuring the default handler for a specific MIME type, to be used by applications built with th Gnome GIO API.
- This module allows configuring the default handler for a specific MIME type, to be used by applications built with the
Gnome GIO API.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -26,28 +26,27 @@ attributes:
options:
mime_type:
description:
- MIME type for which a default handler will be set.
- MIME type for which a default handler will be set.
type: str
required: true
handler:
description:
- Default handler will be set for the MIME type.
- Default handler will be set for the MIME type.
type: str
required: true
notes:
- This module is a thin wrapper around the C(gio mime) command (and subcommand).
- See man gio(1) for more details.
- This module is a thin wrapper around the C(gio mime) command (and subcommand).
- See man gio(1) for more details.
seealso:
- name: C(gio) command manual page
description: Manual page for the command.
link: https://man.archlinux.org/man/gio.1
- name: GIO Documentation
description: Reference documentation for the GIO API..
link: https://docs.gtk.org/gio/
- name: C(gio) command manual page
description: Manual page for the command.
link: https://man.archlinux.org/man/gio.1
- name: GIO Documentation
description: Reference documentation for the GIO API..
link: https://docs.gtk.org/gio/
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Set chrome as the default handler for https
community.general.gio_mime:
mime_type: x-scheme-handler/https
@ -55,23 +54,22 @@ EXAMPLES = """
register: result
"""
RETURN = """
---
RETURN = r"""
handler:
description:
- The handler set as default.
- The handler set as default.
returned: success
type: str
sample: google-chrome.desktop
stdout:
description:
- The output of the C(gio) command.
- The output of the C(gio) command.
returned: success
type: str
sample: Set google-chrome.desktop as the default for x-scheme-handler/https
stderr:
description:
- The error output of the C(gio) command.
- The error output of the C(gio) command.
returned: failure
type: str
sample: 'gio: Failed to load info for handler "never-existed.desktop"'

63
plugins/modules/git_config.py
View File

@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: git_config
author:
- Matthew Gamble (@djmattyg007)
@ -20,11 +19,10 @@ author:
requirements: ['git']
short_description: Update git configuration
description:
- The M(community.general.git_config) module changes git configuration by invoking C(git config).
This is needed if you do not want to use M(ansible.builtin.template) for the entire git
config file (for example because you need to change just C(user.email) in
/etc/.git/config). Solutions involving M(ansible.builtin.command) are cumbersome or
do not work correctly in check mode.
- The M(community.general.git_config) module changes git configuration by invoking C(git config). This is needed if you
do not want to use M(ansible.builtin.template) for the entire git config file (for example because you need to change
just C(user.email) in C(/etc/.git/config)). Solutions involving M(ansible.builtin.command) are cumbersome or do not work
correctly in check mode.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -36,19 +34,17 @@ options:
list_all:
description:
- List all settings (optionally limited to a given O(scope)).
- This option is B(deprecated) and will be removed from community.general 11.0.0.
Please use M(community.general.git_config_info) instead.
- This option is B(deprecated) and will be removed from community.general 11.0.0. Please use M(community.general.git_config_info)
instead.
type: bool
default: false
name:
description:
- The name of the setting. If no value is supplied, the value will
be read from the config if it has been set.
- The name of the setting. If no value is supplied, the value will be read from the config if it has been set.
type: str
repo:
description:
- Path to a git repository for reading and writing values from a
specific repo.
- Path to a git repository for reading and writing values from a specific repo.
type: path
file:
description:
@ -62,36 +58,34 @@ options:
- If this is set to V(local), you must also specify the O(repo) parameter.
- If this is set to V(file), you must also specify the O(file) parameter.
- It defaults to system only when not using O(list_all=true).
choices: [ "file", "local", "global", "system" ]
choices: ["file", "local", "global", "system"]
type: str
state:
description:
- "Indicates the setting should be set/unset.
This parameter has higher precedence than O(value) parameter:
when O(state=absent) and O(value) is defined, O(value) is discarded."
choices: [ 'present', 'absent' ]
- 'Indicates the setting should be set/unset. This parameter has higher precedence than O(value) parameter: when O(state=absent)
and O(value) is defined, O(value) is discarded.'
choices: ['present', 'absent']
default: 'present'
type: str
value:
description:
- When specifying the name of a single setting, supply a value to
set that setting to the given value.
- From community.general 11.0.0 on, O(value) will be required if O(state=present).
To read values, use the M(community.general.git_config_info) module instead.
- When specifying the name of a single setting, supply a value to set that setting to the given value.
- From community.general 11.0.0 on, O(value) will be required if O(state=present). To read values, use the M(community.general.git_config_info)
module instead.
type: str
add_mode:
description:
- Specify if a value should replace the existing value(s) or if the new
value should be added alongside other values with the same name.
- This option is only relevant when adding/replacing values. If O(state=absent) or
values are just read out, this option is not considered.
choices: [ "add", "replace-all" ]
- Specify if a value should replace the existing value(s) or if the new value should be added alongside other values
with the same name.
- This option is only relevant when adding/replacing values. If O(state=absent) or values are just read out, this option
is not considered.
choices: ["add", "replace-all"]
type: str
default: "replace-all"
version_added: 8.1.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Add a setting to ~/.gitconfig
community.general.git_config:
name: alias.ci
@ -147,18 +141,17 @@ EXAMPLES = '''
repo: /etc
scope: local
value: 'root@{{ ansible_fqdn }}'
'''
"""
RETURN = '''
---
RETURN = r"""
config_value:
description: When O(list_all=false) and value is not set, a string containing the value of the setting in name
description: When O(list_all=false) and value is not set, a string containing the value of the setting in name.
returned: success
type: str
sample: "vim"
config_values:
description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings
description: When O(list_all=true), a dict containing key/value pairs of multiple configuration settings.
returned: success
type: dict
sample:
@ -166,7 +159,7 @@ config_values:
color.ui: "auto"
alias.diffc: "diff --cached"
alias.remotev: "remote -v"
'''
"""
from ansible.module_utils.basic import AnsibleModule

29
plugins/modules/git_config_info.py
View File

@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: git_config_info
author:
- Guenther Grill (@guenhter)
@ -19,8 +18,7 @@ version_added: 8.1.0
requirements: ['git']
short_description: Read git configuration
description:
- The M(community.general.git_config_info) module reads the git configuration
by invoking C(git config).
- The M(community.general.git_config_info) module reads the git configuration by invoking C(git config).
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
@ -44,12 +42,12 @@ options:
- If set to V(system), the system git config is used. O(path) is ignored.
- If set to V(local), O(path) must be set to the repo to read from.
- If set to V(file), O(path) must be set to the config file to read from.
choices: [ "global", "system", "local", "file" ]
choices: ["global", "system", "local", "file"]
default: "system"
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Read a system wide config
community.general.git_config_info:
name: core.editor
@ -81,14 +79,13 @@ EXAMPLES = '''
community.general.git_config_info:
scope: file
path: /etc/gitconfig
'''
"""
RETURN = '''
---
RETURN = r"""
config_value:
description: >
When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty.
If a config key such as V(push.pushoption) has more then one entry, just the first one is returned here.
description: >-
When O(name) is set, a string containing the value of the setting in name. If O(name) is not set, empty. If a config key
such as V(push.pushoption) has more then one entry, just the first one is returned here.
returned: success if O(name) is set
type: str
sample: "vim"
@ -97,8 +94,8 @@ config_values:
description:
- This is a dictionary mapping a git configuration setting to a list of its values.
- When O(name) is not set, all configuration settings are returned here.
- When O(name) is set, only the setting specified in O(name) is returned here.
If that setting is not set, the key will still be present, and its value will be an empty list.
- When O(name) is set, only the setting specified in O(name) is returned here. If that setting is not set, the key will
still be present, and its value will be an empty list.
returned: success
type: dict
sample:
@ -106,7 +103,7 @@ config_values:
color.ui: ["auto"]
push.pushoption: ["merge_request.create", "merge_request.draft"]
alias.remotev: ["remote -v"]
'''
"""
from ansible.module_utils.basic import AnsibleModule

71
plugins/modules/github_deploy_key.py
View File

@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: github_deploy_key
author: "Ali (@bincyber)"
short_description: Manages deploy keys for GitHub repositories
description:
- "Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password,
username and password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin
rights on the repository are required."
- Adds or removes deploy keys for GitHub repositories. Supports authentication using username and password, username and
password and 2-factor authentication code (OTP), OAuth2 token, or personal access token. Admin rights on the repository
are required.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -28,7 +27,7 @@ attributes:
options:
github_url:
description:
- The base URL of the GitHub API
- The base URL of the GitHub API.
required: false
type: str
version_added: '0.2.0'
@ -37,19 +36,19 @@ options:
description:
- The name of the individual account or organization that owns the GitHub repository.
required: true
aliases: [ 'account', 'organization' ]
aliases: ['account', 'organization']
type: str
repo:
description:
- The name of the GitHub repository.
required: true
aliases: [ 'repository' ]
aliases: ['repository']
type: str
name:
description:
- The name for the deploy key.
required: true
aliases: [ 'title', 'label' ]
aliases: ['title', 'label']
type: str
key:
description:
@ -58,14 +57,15 @@ options:
type: str
read_only:
description:
- If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to read and write.
- If V(true), the deploy key will only be able to read repository contents. Otherwise, the deploy key will be able to
read and write.
type: bool
default: true
state:
description:
- The state of the deploy key.
default: "present"
choices: [ "present", "absent" ]
choices: ["present", "absent"]
type: str
force:
description:
@ -74,11 +74,12 @@ options:
default: false
username:
description:
- The username to authenticate with. Should not be set when using personal access token
- The username to authenticate with. Should not be set when using personal access token.
type: str
password:
description:
- The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password) combination.
- The password to authenticate with. Alternatively, a personal access token can be used instead of O(username) and O(password)
combination.
type: str
token:
description:
@ -89,10 +90,10 @@ options:
- The 6 digit One Time Password for 2-Factor Authentication. Required together with O(username) and O(password).
type: int
notes:
- "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/."
'''
- "Refer to GitHub's API documentation here: https://developer.github.com/v3/repos/keys/."
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Add a new read-only deploy key to a GitHub repository using basic authentication
community.general.github_deploy_key:
owner: "johndoe"
@ -152,33 +153,33 @@ EXAMPLES = '''
read_only: true
username: "janedoe"
password: "supersecretpassword"
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: the status message describing what occurred
returned: always
type: str
sample: "Deploy key added successfully"
description: The status message describing what occurred.
returned: always
type: str
sample: "Deploy key added successfully"
http_status_code:
description: the HTTP status code returned by the GitHub API
returned: failed
type: int
sample: 400
description: The HTTP status code returned by the GitHub API.
returned: failed
type: int
sample: 400
error:
description: the error message returned by the GitHub API
returned: failed
type: str
sample: "key is already in use"
description: The error message returned by the GitHub API.
returned: failed
type: str
sample: "key is already in use"
id:
description: the key identifier assigned by GitHub for the deploy key
returned: changed
type: int
sample: 24381901
'''
description: The key identifier assigned by GitHub for the deploy key.
returned: changed
type: int
sample: 24381901
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url

26
plugins/modules/github_issue.py
View File

@ -10,7 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: github_issue
short_description: View GitHub issue
description:
@ -40,24 +40,24 @@ options:
type: int
action:
description:
- Get various details about issue depending upon action specified.
- Get various details about issue depending upon action specified.
default: 'get_status'
choices:
- 'get_status'
- get_status
type: str
author:
- Abhijeet Kasurde (@Akasurde)
'''
- Abhijeet Kasurde (@Akasurde)
"""
RETURN = '''
RETURN = r"""
issue_status:
description: State of the GitHub issue
type: str
returned: success
sample: open, closed
'''
description: State of the GitHub issue.
type: str
returned: success
sample: open, closed
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Check if GitHub issue is closed or not
community.general.github_issue:
organization: ansible
@ -70,7 +70,7 @@ EXAMPLES = '''
ansible.builtin.debug:
msg: Do something when issue 23642 is open
when: r.issue_status == 'open'
'''
"""
import json

46
plugins/modules/github_key.py
View File

@ -9,7 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: github_key
short_description: Manage GitHub access keys
description:
@ -29,7 +29,7 @@ options:
type: str
name:
description:
- SSH key name
- SSH key name.
required: true
type: str
pubkey:
@ -44,34 +44,36 @@ options:
type: str
force:
description:
- The default is V(true), which will replace the existing remote key
if it is different than O(pubkey). If V(false), the key will only be
set if no key with the given O(name) exists.
- The default is V(true), which will replace the existing remote key if it is different than O(pubkey). If V(false),
the key will only be set if no key with the given O(name) exists.
type: bool
default: true
author: Robert Estelle (@erydo)
'''
"""
RETURN = '''
RETURN = r"""
deleted_keys:
description: An array of key objects that were deleted. Only present on state=absent
type: list
returned: When state=absent
sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}]
description: An array of key objects that were deleted. Only present on state=absent.
type: list
returned: When state=absent
sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
'read_only': false}]
matching_keys:
description: An array of keys matching the specified name. Only present on state=present
type: list
returned: When state=present
sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}]
description: An array of keys matching the specified name. Only present on state=present.
type: list
returned: When state=present
sample: [{'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
'read_only': false}]
key:
description: Metadata about the key just created. Only present on state=present
type: dict
returned: success
sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ', 'read_only': false}
'''
description: Metadata about the key just created. Only present on state=present.
type: dict
returned: success
sample: {'id': 0, 'key': 'BASE64 encoded key', 'url': 'http://example.com/github key', 'created_at': 'YYYY-MM-DDTHH:MM:SZ',
'read_only': false}
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Read SSH public key to authorize
ansible.builtin.shell: cat /home/foo/.ssh/id_rsa.pub
register: ssh_pub_key
@ -89,7 +91,7 @@ EXAMPLES = '''
name: Access Key for Some Machine
token: '{{ github_access_token }}'
pubkey: "{{ lookup('ansible.builtin.file', '/home/foo/.ssh/id_rsa.pub') }}"
'''
"""
import datetime
import json

138
plugins/modules/github_release.py
View File

@ -9,78 +9,77 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: github_release
short_description: Interact with GitHub Releases
description:
- Fetch metadata about GitHub Releases
- Fetch metadata about GitHub Releases.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
diff_mode:
support: none
check_mode:
support: full
diff_mode:
support: none
options:
token:
description:
- GitHub Personal Access Token for authenticating. Mutually exclusive with O(password).
type: str
user:
description:
- The GitHub account that owns the repository
type: str
required: true
password:
description:
- The GitHub account password for the user. Mutually exclusive with O(token).
type: str
repo:
description:
- Repository name
type: str
required: true
action:
description:
- Action to perform
type: str
required: true
choices: [ 'latest_release', 'create_release' ]
tag:
description:
- Tag name when creating a release. Required when using O(action=create_release).
type: str
target:
description:
- Target of release when creating a release
type: str
name:
description:
- Name of release when creating a release
type: str
body:
description:
- Description of the release when creating a release
type: str
draft:
description:
- Sets if the release is a draft or not. (boolean)
type: bool
default: false
prerelease:
description:
- Sets if the release is a prerelease or not. (boolean)
type: bool
default: false
token:
description:
- GitHub Personal Access Token for authenticating. Mutually exclusive with O(password).
type: str
user:
description:
- The GitHub account that owns the repository.
type: str
required: true
password:
description:
- The GitHub account password for the user. Mutually exclusive with O(token).
type: str
repo:
description:
- Repository name.
type: str
required: true
action:
description:
- Action to perform.
type: str
required: true
choices: ['latest_release', 'create_release']
tag:
description:
- Tag name when creating a release. Required when using O(action=create_release).
type: str
target:
description:
- Target of release when creating a release.
type: str
name:
description:
- Name of release when creating a release.
type: str
body:
description:
- Description of the release when creating a release.
type: str
draft:
description:
- Sets if the release is a draft or not. (boolean).
type: bool
default: false
prerelease:
description:
- Sets if the release is a prerelease or not. (boolean).
type: bool
default: false
author:
- "Adrian Moisey (@adrianmoisey)"
- "Adrian Moisey (@adrianmoisey)"
requirements:
- "github3.py >= 1.0.0a3"
'''
- "github3.py >= 1.0.0a3"
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get latest release of a public repository
community.general.github_release:
user: ansible
@ -111,16 +110,15 @@ EXAMPLES = '''
target: master
name: My Release
body: Some description
"""
'''
RETURN = '''
RETURN = r"""
tag:
description: Version of the created/latest release.
type: str
returned: success
sample: 1.1.0
'''
description: Version of the created/latest release.
type: str
returned: success
sample: 1.1.0
"""
import traceback

68
plugins/modules/github_repo.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: github_repo
short_description: Manage your repositories on Github
version_added: 2.2.0
@ -26,81 +25,82 @@ attributes:
options:
username:
description:
- Username used for authentication.
- This is only needed when not using O(access_token).
- Username used for authentication.
- This is only needed when not using O(access_token).
type: str
required: false
password:
description:
- Password used for authentication.
- This is only needed when not using O(access_token).
- Password used for authentication.
- This is only needed when not using O(access_token).
type: str
required: false
access_token:
description:
- Token parameter for authentication.
- This is only needed when not using O(username) and O(password).
- Token parameter for authentication.
- This is only needed when not using O(username) and O(password).
type: str
required: false
name:
description:
- Repository name.
- Repository name.
type: str
required: true
description:
description:
- Description for the repository.
- Defaults to empty if O(force_defaults=true), which is the default in this module.
- Defaults to empty if O(force_defaults=false) when creating a new repository.
- This is only used when O(state) is V(present).
- Description for the repository.
- Defaults to empty if O(force_defaults=true), which is the default in this module.
- Defaults to empty if O(force_defaults=false) when creating a new repository.
- This is only used when O(state) is V(present).
type: str
required: false
private:
description:
- Whether the repository should be private or not.
- Defaults to V(false) if O(force_defaults=true), which is the default in this module.
- Defaults to V(false) if O(force_defaults=false) when creating a new repository.
- This is only used when O(state=present).
- Whether the repository should be private or not.
- Defaults to V(false) if O(force_defaults=true), which is the default in this module.
- Defaults to V(false) if O(force_defaults=false) when creating a new repository.
- This is only used when O(state=present).
type: bool
required: false
state:
description:
- Whether the repository should exist or not.
- Whether the repository should exist or not.
type: str
default: present
choices: [ absent, present ]
choices: [absent, present]
required: false
organization:
description:
- Organization for the repository.
- When O(state=present), the repository will be created in the current user profile.
- Organization for the repository.
- When O(state=present), the repository will be created in the current user profile.
type: str
required: false
api_url:
description:
- URL to the GitHub API if not using github.com but you own instance.
- URL to the GitHub API if not using github.com but you own instance.
type: str
default: 'https://api.github.com'
version_added: "3.5.0"
force_defaults:
description:
- Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the default.
- The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
- Overwrite current O(description) and O(private) attributes with defaults if set to V(true), which currently is the
default.
- The default for this option will be deprecated in a future version of this collection, and eventually change to V(false).
type: bool
default: true
required: false
version_added: 4.1.0
requirements:
- PyGithub>=1.54
- PyGithub>=1.54
notes:
- For Python 3, PyGithub>=1.54 should be used.
- "For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020)."
- "For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019)."
- For Python 3, PyGithub>=1.54 should be used.
- 'For Python 3.5, PyGithub==1.54 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-54-november-30-2020).'
- 'For Python 2.7, PyGithub==1.45 should be used. More information: U(https://pygithub.readthedocs.io/en/latest/changes.html#version-1-45-december-29-2019).'
author:
- Álvaro Torres Cogollo (@atorrescogollo)
'''
- Álvaro Torres Cogollo (@atorrescogollo)
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a Github repository
community.general.github_repo:
access_token: mytoken
@ -120,14 +120,14 @@ EXAMPLES = '''
name: myrepo
state: absent
register: result
'''
"""
RETURN = '''
RETURN = r"""
repo:
description: Repository information as JSON. See U(https://docs.github.com/en/rest/reference/repos#get-a-repository).
returned: success and O(state=present)
type: dict
'''
"""
import traceback
from ansible.module_utils.basic import AnsibleModule, missing_required_lib

50
plugins/modules/github_webhook.py
View File

@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: github_webhook
short_description: Manage GitHub webhooks
description:
- "Create and delete GitHub webhooks"
- Create and delete GitHub webhooks.
requirements:
- "PyGithub >= 1.3.5"
extends_documentation_fragment:
@ -26,22 +25,22 @@ attributes:
options:
repository:
description:
- Full name of the repository to configure a hook for
- Full name of the repository to configure a hook for.
type: str
required: true
aliases:
- repo
url:
description:
- URL to which payloads will be delivered
- URL to which payloads will be delivered.
type: str
required: true
content_type:
description:
- The media type used to serialize the payloads
- The media type used to serialize the payloads.
type: str
required: false
choices: [ form, json ]
choices: [form, json]
default: form
secret:
description:
@ -50,61 +49,57 @@ options:
required: false
insecure_ssl:
description:
- >
Flag to indicate that GitHub should skip SSL verification when calling
the hook.
- Flag to indicate that GitHub should skip SSL verification when calling the hook.
required: false
type: bool
default: false
events:
description:
- >
A list of GitHub events the hook is triggered for. Events are listed at
U(https://developer.github.com/v3/activity/events/types/). Required
unless O(state=absent)
- A list of GitHub events the hook is triggered for. Events are listed at U(https://developer.github.com/v3/activity/events/types/).
Required unless O(state=absent).
required: false
type: list
elements: str
active:
description:
- Whether or not the hook is active
- Whether or not the hook is active.
required: false
type: bool
default: true
state:
description:
- Whether the hook should be present or absent
- Whether the hook should be present or absent.
type: str
required: false
choices: [ absent, present ]
choices: [absent, present]
default: present
user:
description:
- User to authenticate to GitHub as
- User to authenticate to GitHub as.
type: str
required: true
password:
description:
- Password to authenticate to GitHub with
- Password to authenticate to GitHub with.
type: str
required: false
token:
description:
- Token to authenticate to GitHub with
- Token to authenticate to GitHub with.
type: str
required: false
github_url:
description:
- Base URL of the GitHub API
- Base URL of the GitHub API.
type: str
required: false
default: https://api.github.com
author:
- "Chris St. Pierre (@stpierre)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a new webhook that triggers on push (password auth)
community.general.github_webhook:
repository: ansible/ansible
@ -135,16 +130,15 @@ EXAMPLES = '''
state: absent
user: "{{ github_user }}"
password: "{{ github_password }}"
'''
"""
RETURN = '''
---
RETURN = r"""
hook_id:
description: The GitHub ID of the hook created/updated
description: The GitHub ID of the hook created/updated.
returned: when state is 'present'
type: int
sample: 6206
'''
"""
import traceback

28
plugins/modules/github_webhook_info.py
View File

@ -8,12 +8,11 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: github_webhook_info
short_description: Query information about GitHub webhooks
description:
- "Query information about GitHub webhooks"
- Query information about GitHub webhooks.
requirements:
- "PyGithub >= 1.3.5"
extends_documentation_fragment:
@ -22,38 +21,38 @@ extends_documentation_fragment:
options:
repository:
description:
- Full name of the repository to configure a hook for
- Full name of the repository to configure a hook for.
type: str
required: true
aliases:
- repo
user:
description:
- User to authenticate to GitHub as
- User to authenticate to GitHub as.
type: str
required: true
password:
description:
- Password to authenticate to GitHub with
- Password to authenticate to GitHub with.
type: str
required: false
token:
description:
- Token to authenticate to GitHub with
- Token to authenticate to GitHub with.
type: str
required: false
github_url:
description:
- Base URL of the github api
- Base URL of the GitHub API.
type: str
required: false
default: https://api.github.com
author:
- "Chris St. Pierre (@stpierre)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: List hooks for a repository (password auth)
community.general.github_webhook_info:
repository: ansible/ansible
@ -68,12 +67,11 @@ EXAMPLES = '''
token: "{{ github_user_api_token }}"
github_url: https://github.example.com/api/v3/
register: myrepo_webhooks
'''
"""
RETURN = '''
---
RETURN = r"""
hooks:
description: A list of hooks that exist for the repo
description: A list of hooks that exist for the repo.
returned: always
type: list
elements: dict
@ -88,7 +86,7 @@ hooks:
"id": 6206,
"last_response": {"status": "active", "message": "OK", "code": 200}
}
'''
"""
import traceback

13
plugins/modules/gitlab_branch.py
View File

@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_branch
short_description: Create or delete a branch
version_added: 4.2.0
@ -50,10 +50,10 @@ options:
- Reference branch to create from.
- This must be specified if O(state=present).
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create branch branch2 from main
community.general.gitlab_branch:
api_url: https://gitlab.com
@ -70,11 +70,10 @@ EXAMPLES = '''
project: "group1/project1"
branch: branch2
state: absent
"""
'''
RETURN = '''
'''
RETURN = r"""
"""
import traceback

29
plugins/modules/gitlab_deploy_key.py
View File

@ -11,11 +11,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_deploy_key
short_description: Manages GitLab project deploy keys
description:
- Adds, updates and removes project deploy keys
- Adds, updates and removes project deploy keys.
author:
- Marcus Watkins (@marwatk)
- Guillaume Martinez (@Lunik)
@ -45,7 +45,7 @@ options:
type: str
key:
description:
- Deploy key
- Deploy key.
required: true
type: str
can_push:
@ -55,14 +55,14 @@ options:
default: false
state:
description:
- When V(present) the deploy key added to the project if it doesn't exist.
- When V(present) the deploy key added to the project if it does not exist.
- When V(absent) it will be removed from the project if it exists.
default: present
type: str
choices: [ "present", "absent" ]
'''
choices: ["present", "absent"]
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "Adding a project deploy key"
community.general.gitlab_deploy_key:
api_url: https://gitlab.example.com/
@ -88,32 +88,31 @@ EXAMPLES = '''
project: "my_group/my_project"
state: absent
key: "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9w..."
"""
'''
RETURN = '''
RETURN = r"""
msg:
description: Success or failure message
description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
description: json parsed response from the server
description: JSON-parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: key is already in use"
deploy_key:
description: API object
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

31
plugins/modules/gitlab_group.py
View File

@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gitlab_group
short_description: Creates/updates/deletes GitLab Groups
description:
@ -97,12 +96,12 @@ options:
type: str
parent:
description:
- Allow to create subgroups
- Id or Full path of parent group in the form of group/name
- Allow to create subgroups.
- Id or Full path of parent group in the form of group/name.
type: str
path:
description:
- The path of the group you want to create, this will be api_url/group_path
- 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.
type: str
prevent_forking_outside_group:
@ -146,7 +145,7 @@ options:
version_added: 3.7.0
state:
description:
- create or delete group.
- Create or delete group.
- Possible values are present and absent.
default: present
type: str
@ -164,7 +163,7 @@ options:
version_added: 9.5.0
visibility:
description:
- Default visibility of the group
- Default visibility of the group.
choices: ["private", "internal", "public"]
default: private
type: str
@ -176,9 +175,9 @@ options:
choices: ["enabled", "private", "disabled"]
type: str
version_added: 9.5.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "Delete GitLab Group"
community.general.gitlab_group:
api_url: https://gitlab.example.com/
@ -221,31 +220,31 @@ EXAMPLES = '''
project_creation_level: noone
auto_devops_enabled: false
subgroup_creation_level: maintainer
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Success or failure message
description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
description: json parsed response from the server
description: JSON-parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
group:
description: API object
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

22
plugins/modules/gitlab_group_access_token.py
View File

@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: gitlab_group_access_token
short_description: Manages GitLab group access tokens
version_added: 8.4.0
@ -27,11 +27,10 @@ extends_documentation_fragment:
- community.general.gitlab
- community.general.attributes
notes:
- Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated.
Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens
will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.
- Token matching is done by comparing O(name) option.
attributes:
check_mode:
support: full
@ -56,7 +55,8 @@ options:
type: list
elements: str
aliases: ["scope"]
choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"]
choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner",
"ai_features", "k8s_proxy"]
access_level:
description:
- Access level of the access token.
@ -84,10 +84,10 @@ options:
- When V(absent) it will be removed from the group if it exists.
default: present
type: str
choices: [ "present", "absent" ]
'''
choices: ["present", "absent"]
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: "Creating a group access token"
community.general.gitlab_group_access_token:
api_url: https://gitlab.example.com/
@ -131,16 +131,16 @@ EXAMPLES = r'''
- write_repository
recreate: state_change
state: present
'''
"""
RETURN = r'''
RETURN = r"""
access_token:
description:
- API object.
- Only contains the value of the token if the token was created or recreated.
returned: success and O(state=present)
type: dict
'''
"""
from datetime import datetime

15
plugins/modules/gitlab_group_members.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: gitlab_group_members
short_description: Manage group members on GitLab Server
description:
@ -81,16 +80,16 @@ options:
type: str
purge_users:
description:
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
If omitted do not purge orphaned members.
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted
do not purge orphaned members.
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
version_added: 3.6.0
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Add a user to a GitLab Group
community.general.gitlab_group_members:
api_url: 'https://gitlab.example.com'
@ -152,9 +151,9 @@ EXAMPLES = r'''
- name: user2
access_level: maintainer
state: absent
'''
"""
RETURN = r''' # '''
RETURN = r""" # """
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

26
plugins/modules/gitlab_group_variable.py
View File

@ -9,15 +9,15 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: gitlab_group_variable
short_description: Creates, updates, or deletes GitLab groups variables
version_added: 1.2.0
description:
- Creates a group variable if it does not exist.
- When a group variable does exist, its value will be updated when the values are different.
- Variables which are untouched in the playbook, but are not untouched in the GitLab group,
they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
- Variables which are untouched in the playbook, but are not untouched in the GitLab group, they stay untouched (O(purge=false))
or will be deleted (O(purge=true)).
author:
- Florent Madiot (@scodeman)
requirements:
@ -53,8 +53,8 @@ options:
vars:
description:
- When the list element is a simple key-value pair, masked, raw and protected will be set to false.
- When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can
have full control about whether a value should be masked, raw, protected or both.
- When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full
control about whether a value should be masked, raw, protected or both.
- Support for group variables requires GitLab >= 9.5.
- Support for environment_scope requires GitLab Premium >= 13.11.
- Support for protected values requires GitLab >= 9.3.
@ -62,8 +62,8 @@ options:
- Support for raw values requires GitLab >= 15.7.
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- When a value is masked, it must be in Base64 and have a length of at least 8 characters.
See GitLab documentation on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
- When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation
on acceptable values for a masked variable (U(https://docs.gitlab.com/ce/ci/variables/#masked-variables)).
default: {}
type: dict
variables:
@ -106,17 +106,17 @@ options:
description:
- Whether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
choices: [ "env_var", "file" ]
choices: ["env_var", "file"]
default: env_var
environment_scope:
description:
- The scope for the variable.
type: str
default: '*'
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_group_variable:
api_url: https://gitlab.com
@ -173,9 +173,9 @@ EXAMPLES = r'''
state: absent
vars:
ACCESS_KEY_ID: abc123
'''
"""
RETURN = r'''
RETURN = r"""
group_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@ -201,7 +201,7 @@ group_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

31
plugins/modules/gitlab_hook.py
View File

@ -11,12 +11,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gitlab_hook
short_description: Manages GitLab project hooks
description:
- Adds, updates and removes project hook
- Adds, updates and removes project hook.
author:
- Marcus Watkins (@marwatk)
- Guillaume Martinez (@Lunik)
@ -46,11 +45,11 @@ options:
type: str
state:
description:
- When V(present) the hook will be updated to match the input or created if it doesn't exist.
- When V(present) the hook will be updated to match the input or created if it does not exist.
- When V(absent) hook will be deleted if it exists.
default: present
type: str
choices: [ "present", "absent" ]
choices: ["present", "absent"]
push_events:
description:
- Trigger hook on push events.
@ -58,7 +57,7 @@ options:
default: true
push_events_branch_filter:
description:
- Branch name of wildcard to trigger hook on push events
- Branch name of wildcard to trigger hook on push events.
type: str
version_added: '0.2.0'
default: ''
@ -107,7 +106,7 @@ options:
- Whether GitLab will do SSL verification when triggering the hook.
type: bool
default: false
aliases: [ enable_ssl_verification ]
aliases: [enable_ssl_verification]
token:
description:
- Secret token to validate hook messages at the receiver.
@ -115,9 +114,9 @@ options:
- Will show up in the X-GitLab-Token HTTP request header.
required: false
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "Adding a project hook"
community.general.gitlab_hook:
api_url: https://gitlab.example.com/
@ -144,31 +143,31 @@ EXAMPLES = '''
project: 10
hook_url: "https://my-ci-server.example.com/gitlab-hook"
state: absent
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Success or failure message
description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
description: json parsed response from the server
description: Json parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
hook:
description: API object
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

18
plugins/modules/gitlab_instance_variable.py
View File

@ -10,7 +10,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: gitlab_instance_variable
short_description: Creates, updates, or deletes GitLab instance variables
version_added: 7.1.0
@ -18,8 +18,8 @@ description:
- Creates a instance variable if it does not exist.
- When a instance variable does exist, its value will be updated if the values are different.
- Support for instance variables requires GitLab >= 13.0.
- Variables which are not mentioned in the modules options, but are present on the GitLab instance,
will either stay (O(purge=false)) or will be deleted (O(purge=true)).
- Variables which are not mentioned in the modules options, but are present on the GitLab instance, will either stay (O(purge=false))
or will be deleted (O(purge=true)).
author:
- Benedikt Braunger (@benibr)
requirements:
@ -78,12 +78,12 @@ options:
description:
- Whether a variable is an environment variable (V(env_var)) or a file (V(file)).
type: str
choices: [ "env_var", "file" ]
choices: ["env_var", "file"]
default: env_var
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_instance_variable:
api_url: https://gitlab.com
@ -105,9 +105,9 @@ EXAMPLES = r'''
state: absent
variables:
- name: ACCESS_KEY_ID
'''
"""
RETURN = r'''
RETURN = r"""
instance_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@ -133,7 +133,7 @@ instance_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

18
plugins/modules/gitlab_issue.py
View File

@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_issue
short_description: Create, update, or delete GitLab issues
version_added: '8.1.0'
@ -97,10 +97,10 @@ options:
- A title for the issue. The title is used as a unique identifier to ensure idempotency.
type: str
required: true
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create Issue
community.general.gitlab_issue:
api_url: https://gitlab.com
@ -109,10 +109,10 @@ EXAMPLES = '''
title: "Ansible demo Issue"
description: "Demo Issue description"
labels:
- Ansible
- Demo
- Ansible
- Demo
assignee_ids:
- testassignee
- testassignee
state_filter: "opened"
state: present
@ -124,9 +124,9 @@ EXAMPLES = '''
title: "Ansible demo Issue"
state_filter: "opened"
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
msg:
description: Success or failure message.
returned: always
@ -137,7 +137,7 @@ issue:
description: API object.
returned: success
type: dict
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

24
plugins/modules/gitlab_label.py
View File

@ -7,9 +7,9 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_label
short_description: Creates/updates/deletes GitLab Labels belonging to project or group.
short_description: Creates/updates/deletes GitLab Labels belonging to project or group
version_added: 8.3.0
description:
- When a label does not exist, it will be created.
@ -45,12 +45,12 @@ options:
required: false
project:
description:
- The path and name of the project. Either this or O(group) is required.
- The path and name of the project. Either this or O(group) is required.
required: false
type: str
group:
description:
- The path of the group. Either this or O(project) is required.
- The path of the group. Either this or O(project) is required.
required: false
type: str
labels:
@ -76,21 +76,21 @@ options:
- Integer value to give priority to the label.
type: int
required: false
default: null
default:
description:
description:
- Label's description.
type: str
default: null
default:
new_name:
description:
- Optional field to change label's name.
type: str
default: null
'''
default:
"""
EXAMPLES = '''
EXAMPLES = r"""
# same project's task can be executed for group
- name: Create one Label
community.general.gitlab_label:
@ -185,9 +185,9 @@ EXAMPLES = '''
labels:
- name: label-abc123
- name: label-two
'''
"""
RETURN = '''
RETURN = r"""
labels:
description: Four lists of the labels which were added, updated, removed or exist.
returned: success
@ -217,7 +217,7 @@ labels_obj:
description: API object.
returned: success
type: dict
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

17
plugins/modules/gitlab_merge_request.py
View File

@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_merge_request
short_description: Create, update, or delete GitLab merge requests
version_added: 7.1.0
@ -21,8 +21,7 @@ description:
- When a single merge request does exist, it will be updated if the provided parameters are different.
- When a single merge request does exist and O(state=absent), the merge request will be deleted.
- When multiple merge requests are detected, the task fails.
- Existing merge requests are matched based on O(title), O(source_branch), O(target_branch),
and O(state_filter) filters.
- Existing merge requests are matched based on O(title), O(source_branch), O(target_branch), and O(state_filter) filters.
author:
- zvaraondrej (@zvaraondrej)
requirements:
@ -102,10 +101,10 @@ options:
- Comma separated list of reviewers usernames omitting V(@) character.
- Set to empty string to unassign all reviewers.
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create Merge Request from branch1 to branch2
community.general.gitlab_merge_request:
api_url: https://gitlab.com
@ -117,7 +116,7 @@ EXAMPLES = '''
description: "Demo MR description"
labels: "Ansible,Demo"
state_filter: "opened"
remove_source_branch: True
remove_source_branch: true
state: present
- name: Delete Merge Request from branch1 to branch2
@ -130,9 +129,9 @@ EXAMPLES = '''
title: "Ansible demo MR"
state_filter: "opened"
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
msg:
description: Success or failure message.
returned: always
@ -143,7 +142,7 @@ mr:
description: API object.
returned: success
type: dict
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

12
plugins/modules/gitlab_milestone.py
View File

@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_milestone
short_description: Creates/updates/deletes GitLab Milestones belonging to project or group
version_added: 8.3.0
@ -83,10 +83,10 @@ options:
- Milestone's description.
type: str
default: null
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# same project's task can be executed for group
- name: Create one milestone
community.general.gitlab_milestone:
@ -169,9 +169,9 @@ EXAMPLES = '''
milestones:
- title: milestone-abc123
- title: milestone-two
'''
"""
RETURN = '''
RETURN = r"""
milestones:
description: Four lists of the milestones which were added, updated, removed or exist.
returned: success
@ -201,7 +201,7 @@ milestones_obj:
description: API object.
returned: success
type: dict
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

20
plugins/modules/gitlab_project.py
View File

@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: gitlab_project
short_description: Creates/updates/deletes GitLab Projects
description:
@ -179,8 +178,7 @@ options:
default: true
lfs_enabled:
description:
- Enable Git large file systems to manages large files such
as audio, video, and graphics files.
- Enable Git large file systems to manages large files such as audio, video, and graphics files.
type: bool
required: false
default: false
@ -331,9 +329,9 @@ options:
- If an wiki for this project should be available or not.
type: bool
default: true
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Create GitLab Project
community.general.gitlab_project:
api_url: https://gitlab.example.com/
@ -378,9 +376,9 @@ EXAMPLES = r'''
api_password: "{{ initial_root_password }}"
name: my_second_project
group: "10481470"
'''
"""
RETURN = r'''
RETURN = r"""
msg:
description: Success or failure message.
returned: always
@ -388,12 +386,12 @@ msg:
sample: "Success"
result:
description: json parsed response from the server.
description: JSON-parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API.
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
@ -402,7 +400,7 @@ project:
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec

22
plugins/modules/gitlab_project_access_token.py
View File

@ -12,7 +12,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: gitlab_project_access_token
short_description: Manages GitLab project access tokens
version_added: 8.4.0
@ -27,11 +27,10 @@ extends_documentation_fragment:
- community.general.gitlab
- community.general.attributes
notes:
- Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated.
Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens
will be recreated is controlled by the O(recreate) option, which defaults to V(never).
- Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.
- Token matching is done by comparing O(name) option.
attributes:
check_mode:
support: full
@ -56,7 +55,8 @@ options:
type: list
elements: str
aliases: ["scope"]
choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"]
choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner",
"ai_features", "k8s_proxy"]
access_level:
description:
- Access level of the access token.
@ -84,10 +84,10 @@ options:
- When V(absent) it will be removed from the project if it exists.
default: present
type: str
choices: [ "present", "absent" ]
'''
choices: ["present", "absent"]
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: "Creating a project access token"
community.general.gitlab_project_access_token:
api_url: https://gitlab.example.com/
@ -131,16 +131,16 @@ EXAMPLES = r'''
- write_repository
recreate: state_change
state: present
'''
"""
RETURN = r'''
RETURN = r"""
access_token:
description:
- API object.
- Only contains the value of the token if the token was created or recreated.
returned: success and O(state=present)
type: dict
'''
"""
from datetime import datetime

13
plugins/modules/gitlab_project_badge.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: gitlab_project_badge
short_description: Manage project badges on GitLab Server
version_added: 6.1.0
@ -57,9 +56,9 @@ options:
- A badge is identified by this URL.
required: true
type: str
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Add a badge to a GitLab Project
community.general.gitlab_project_badge:
api_url: 'https://example.gitlab.com'
@ -77,9 +76,9 @@ EXAMPLES = r'''
state: absent
link_url: 'https://example.gitlab.com/%{project_path}'
image_url: 'https://example.gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg'
'''
"""
RETURN = '''
RETURN = r"""
badge:
description: The badge information.
returned: when O(state=present)
@ -91,7 +90,7 @@ badge:
rendered_link_url: 'http://example.com/ci_status.svg?project=example-org/example-project&ref=master'
rendered_image_url: 'https://shields.io/my/badge'
kind: project
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

15
plugins/modules/gitlab_project_members.py
View File

@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: gitlab_project_members
short_description: Manage project members on GitLab Server
version_added: 2.2.0
@ -82,16 +81,16 @@ options:
type: str
purge_users:
description:
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list.
If omitted do not purge orphaned members.
- Adds/remove users of the given access_level to match the given O(gitlab_user)/O(gitlab_users_access) list. If omitted
do not purge orphaned members.
- Is only used when O(state=present).
type: list
elements: str
choices: ['guest', 'reporter', 'developer', 'maintainer']
version_added: 3.7.0
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Add a user to a GitLab Project
community.general.gitlab_project_members:
api_url: 'https://gitlab.example.com'
@ -154,9 +153,9 @@ EXAMPLES = r'''
- name: user2
access_level: maintainer
state: absent
'''
"""
RETURN = r''' # '''
RETURN = r""" # """
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

24
plugins/modules/gitlab_project_variable.py
View File

@ -7,14 +7,14 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_project_variable
short_description: Creates/updates/deletes GitLab Projects Variables
description:
- When a project variable does not exist, it will be created.
- When a project variable does exist, its value will be updated when the values are different.
- Variables which are untouched in the playbook, but are not untouched in the GitLab project,
they stay untouched (O(purge=false)) or will be deleted (O(purge=true)).
- Variables which are untouched in the playbook, but are not untouched in the GitLab project, they stay untouched (O(purge=false))
or will be deleted (O(purge=true)).
author:
- "Markus Bergholz (@markuman)"
requirements:
@ -51,8 +51,8 @@ options:
vars:
description:
- When the list element is a simple key-value pair, masked, raw and protected will be set to false.
- When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can
have full control about whether a value should be masked, raw, protected or both.
- When the list element is a dict with the keys C(value), C(masked), C(raw) and C(protected), the user can have full
control about whether a value should be masked, raw, protected or both.
- Support for protected values requires GitLab >= 9.3.
- Support for masked values requires GitLab >= 11.10.
- Support for raw values requires GitLab >= 15.7.
@ -61,8 +61,8 @@ options:
- A C(value) must be a string or a number.
- Field C(variable_type) must be a string with either V(env_var), which is the default, or V(file).
- Field C(environment_scope) must be a string defined by scope environment.
- When a value is masked, it must be in Base64 and have a length of at least 8 characters.
See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
- When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation
on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).
default: {}
type: dict
variables:
@ -116,10 +116,10 @@ options:
- Support for O(variables[].environment_scope) requires GitLab Premium >= 13.11.
type: str
default: '*'
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Set or update some CI/CD variables
community.general.gitlab_project_variable:
api_url: https://gitlab.com
@ -190,9 +190,9 @@ EXAMPLES = '''
state: absent
vars:
ACCESS_KEY_ID: abc123
'''
"""
RETURN = '''
RETURN = r"""
project_variable:
description: Four lists of the variablenames which were added, updated, removed or exist.
returned: always
@ -218,7 +218,7 @@ project_variable:
returned: always
type: list
sample: ['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

13
plugins/modules/gitlab_protected_branch.py
View File

@ -7,7 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
module: gitlab_protected_branch
short_description: Manage protection of existing branches
version_added: 3.4.0
@ -58,10 +58,10 @@ options:
default: maintainer
type: str
choices: ["maintainer", "developer", "nobody"]
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create protected branch on main
community.general.gitlab_protected_branch:
api_url: https://gitlab.com
@ -70,11 +70,10 @@ EXAMPLES = '''
name: main
merge_access_levels: maintainer
push_access_level: nobody
"""
'''
RETURN = '''
'''
RETURN = r"""
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.api import basic_auth_argument_spec

59
plugins/modules/gitlab_runner.py
View File

@ -10,33 +10,31 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gitlab_runner
short_description: Create, modify and delete GitLab Runners
description:
- Register, update and delete runners on GitLab Server side with the GitLab API.
- All operations are performed using the GitLab API v4.
- For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html)
and U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
- A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at
U(https://$GITLAB_URL/profile/personal_access_tokens).
- A valid registration token is required for registering a new runner.
To create shared runners, you need to ask your administrator to give you this token.
It can be found at U(https://$GITLAB_URL/admin/runners/).
- This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through its API.
Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command
- For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html) and
U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
- A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web
interface at U(https://$GITLAB_URL/profile/personal_access_tokens).
- A valid registration token is required for registering a new runner. To create shared runners, you need to ask your administrator
to give you this token. It can be found at U(https://$GITLAB_URL/admin/runners/).
- This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through
its API. Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command.
notes:
- To create a new runner at least the O(api_token), O(description) and O(api_url) options are required.
- Runners need to have unique descriptions, since this attribute is used as key for idempotency
- Runners need to have unique descriptions, since this attribute is used as key for idempotency.
author:
- Samy Coenen (@SamyCoenen)
- Guillaume Martinez (@Lunik)
requirements:
- python-gitlab >= 1.5.0 for legacy runner registration workflow
(runner registration token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated))
- python-gitlab >= 4.0.0 for new runner registration workflow
(runner authentication token - U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token))
- python-gitlab >= 1.5.0 for legacy runner registration workflow (runner registration token -
U(https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated))
- python-gitlab >= 4.0.0 for new runner registration workflow (runner authentication token -
U(https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token))
extends_documentation_fragment:
- community.general.auth_basic
- community.general.gitlab
@ -73,7 +71,8 @@ options:
- name
state:
description:
- Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name.
- Make sure that the runner with the same name exists with the same configuration or delete the runner with the same
name.
required: false
default: present
choices: ["present", "absent"]
@ -118,12 +117,12 @@ options:
access_level:
description:
- Determines if a runner can pick up jobs only from protected branches.
- If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and
is only applied on updates.
- If O(access_level_on_creation) is not explicitly set to V(true), this option is ignored on registration and is only
applied on updates.
- If set to V(not_protected), runner can pick up jobs from both protected and unprotected branches.
- If set to V(ref_protected), runner can pick up jobs only from protected branches.
- Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general 8.0.0.
If this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set
- Before community.general 8.0.0 the default was V(ref_protected). This was changed to no default in community.general
8.0.0. If this option is not specified explicitly, GitLab will use V(not_protected) on creation, and the value set
will not be changed on any updates.
required: false
choices: ["not_protected", "ref_protected"]
@ -156,9 +155,9 @@ options:
default: []
type: list
elements: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create an instance-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
@ -234,31 +233,31 @@ EXAMPLES = '''
state: present
project: mygroup/mysubgroup/myproject
register: runner # Register module output to run C(gitlab-runner register) command in another task
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Success or failure message
description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
description: json parsed response from the server
description: JSON-parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
runner:
description: API object
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule

36
plugins/modules/gitlab_user.py
View File

@ -10,8 +10,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gitlab_user
short_description: Creates/updates/deletes/blocks/unblocks GitLab Users
description:
@ -88,13 +87,8 @@ options:
type: str
access_level:
description:
- The access level to the group. One of the following can be used.
- guest
- reporter
- developer
- master (alias for maintainer)
- maintainer
- owner
- The access level to the group.
- The value V(master) is an alias for V(maintainer).
default: guest
type: str
choices: ["guest", "reporter", "developer", "master", "maintainer", "owner"]
@ -128,7 +122,7 @@ options:
suboptions:
provider:
description:
- The name of the external identity provider
- The name of the external identity provider.
type: str
extern_uid:
description:
@ -143,9 +137,9 @@ options:
type: bool
default: false
version_added: 3.3.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: "Delete GitLab User"
community.general.gitlab_user:
api_url: https://gitlab.example.com/
@ -179,8 +173,8 @@ EXAMPLES = '''
password: mysecretpassword
email: me@example.com
identities:
- provider: Keycloak
extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc
- provider: Keycloak
extern_uid: f278f95c-12c7-4d51-996f-758cc2eb11bc
state: present
group: super_group/mon_group
access_level: owner
@ -198,31 +192,31 @@ EXAMPLES = '''
api_token: "{{ access_token }}"
username: myusername
state: unblocked
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Success or failure message
description: Success or failure message.
returned: always
type: str
sample: "Success"
result:
description: json parsed response from the server
description: JSON-parsed response from the server.
returned: always
type: dict
error:
description: the error message returned by the GitLab API
description: The error message returned by the GitLab API.
returned: failed
type: str
sample: "400: path is already in use"
user:
description: API object
description: API object.
returned: always
type: dict
'''
"""
from ansible.module_utils.api import basic_auth_argument_spec

22
plugins/modules/grove.py
View File

@ -9,13 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: grove
short_description: Sends a notification to a grove.io channel
description:
- The C(grove) module sends a message for a service to a Grove.io
channel.
- The C(grove) module sends a message for a service to a Grove.io channel.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -32,7 +30,7 @@ options:
service:
type: str
description:
- Name of the service (displayed as the "user" in the message)
- Name of the service (displayed as the "user" in the message).
required: false
default: ansible
message_content:
@ -44,29 +42,29 @@ options:
url:
type: str
description:
- Service URL for the web client
- Service URL for the web client.
required: false
icon_url:
type: str
description:
- Icon for the service
- Icon for the service.
required: false
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be used
on personally controlled sites using self-signed certificates.
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
self-signed certificates.
default: true
type: bool
author: "Jonas Pfenniger (@zimbatm)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Sends a notification to a grove.io channel
community.general.grove:
channel_token: 6Ph62VBBJOccmtTPZbubiPzdrhipZXtg
service: my-app
message: 'deployed {{ target }}'
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.six.moves.urllib.parse import urlencode

52
plugins/modules/gunicorn.py
View File

@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: gunicorn
short_description: Run gunicorn with various settings
description:
- Starts gunicorn with the parameters specified. Common settings for gunicorn
configuration are supported. For additional configuration use a config file
See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more
options. It's recommended to always use the chdir option to avoid problems
with the location of the app.
- Starts gunicorn with the parameters specified. Common settings for gunicorn configuration are supported. For additional
configuration use a config file See U(https://gunicorn-docs.readthedocs.io/en/latest/settings.html) for more options.
It's recommended to always use the chdir option to avoid problems with the location of the app.
requirements: [gunicorn]
author:
- "Alejandro Gomez (@agmezr)"
- "Alejandro Gomez (@agmezr)"
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: none
@ -40,37 +37,36 @@ options:
type: path
aliases: ['virtualenv']
description:
- 'Path to the virtualenv directory.'
- Path to the virtualenv directory.
config:
type: path
description:
- 'Path to the gunicorn configuration file.'
- Path to the gunicorn configuration file.
aliases: ['conf']
chdir:
type: path
description:
- 'Chdir to specified directory before apps loading.'
- Chdir to specified directory before apps loading.
pid:
type: path
description:
- 'A filename to use for the PID file. If not set and not found on the configuration file a tmp
pid file will be created to check a successful run of gunicorn.'
- A filename to use for the PID file. If not set and not found on the configuration file a tmp pid file will be created
to check a successful run of gunicorn.
worker:
type: str
choices: ['sync', 'eventlet', 'gevent', 'tornado ', 'gthread', 'gaiohttp']
description:
- 'The type of workers to use. The default class (sync) should handle most "normal" types of workloads.'
- The type of workers to use. The default class (sync) should handle most "normal" types of workloads.
user:
type: str
description:
- 'Switch worker processes to run as this user.'
- Switch worker processes to run as this user.
notes:
- If not specified on config file, a temporary error log will be created on /tmp dir.
Please make sure you have write access in /tmp dir. Not needed but will help you to
identify any problem with configuration.
'''
- If not specified on config file, a temporary error log will be created on /tmp dir. Please make sure you have write access
in /tmp dir. Not needed but will help you to identify any problem with configuration.
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Simple gunicorn run example
community.general.gunicorn:
app: 'wsgi'
@ -96,15 +92,15 @@ EXAMPLES = '''
venv: '/workspace/example/venv'
pid: '/workspace/example/gunicorn.pid'
user: 'ansible'
'''
"""
RETURN = '''
RETURN = r"""
gunicorn:
description: process id of gunicorn
returned: changed
type: str
sample: "1234"
'''
description: Process id of gunicorn.
returned: changed
type: str
sample: "1234"
"""
import os
import time